alcove

name: alcove description: "HTTP API-based documentation server (always running). Questions about project architecture, conventions, decisions, code structure, tech debt, env config, progress, or doc health. Also: init project, audit docs, lint, validate, promote note, rebuild index, search vaults."

HTTP API-based documentation server (always running). Auto-detects project by matching CWD against DOCS_ROOT folders.

Paths

All paths are resolved at runtime. ALCOVE_HOME env var overrides the default ~/.alcove.

Name	Resolved Path	Description
ALCOVE_HOME	`~/.alcove`	Root of all alcove data
Docs Root	`~/.alcove/docs`	Project documentation directories
Vaults Root	`~/.alcove/vaults`	Knowledge base vaults
Config	`~/.alcove/config.toml`	Global configuration file
Project Docs	`~/.alcove/docs/{project}/`	Per-project documentation

Quick resolution from CLI:

alcove path              # show all resolved paths
alcove path --json       # JSON output (for scripts/AI)
alcove path docs         # docs root only
alcove path vaults       # vaults root only

Prerequisites

The alcove API server must be running. Check and start with:

alcove api status   # check if server is running
alcove api start    # start if not running

Resolve URL and token once at the start of every session:

eval $(alcove api env)
# sets ALCOVE_URL=http://127.0.0.1:<port>  (always)
# sets ALCOVE_TOKEN=<token>                (only if configured)

All commands below use $ALCOVE_URL. If $ALCOVE_TOKEN is set, add -H "Authorization: Bearer $ALCOVE_TOKEN" to every request.

Arguments

Arg	Action
`verify` / `rag status`	1) `alcove api status` — check daemon is running 2) `eval $(alcove api env)` — resolve URL + token 3) `curl -s $ALCOVE_URL/health` — print health response

When to Use

Any question about project design, status, conventions, decisions, env config, tech debt, code structure, or doc health. Check alcove before answering, not after.

Document Routing

IMPORTANT: This table maps question types to document filenames. When users ask these questions, SEARCH first — do not directly fetch files.

Question	Search Keywords
"What does this do?"	product requirements PRD
"How is this built?" / code structure	architecture code structure CODE_INDEX
"What's the status?"	progress PROGRESS status
"Why was X chosen?"	decisions DECISIONS rationale
"What style to use?"	conventions CONVENTIONS style guide
"What env vars needed?"	SECRETS_MAP env vars environment
"Any known issues?"	technical debt DEBT backlog issues

Workflow: Search → read results. Never fetch PRD.md, ARCHITECTURE.md etc. directly based on this table alone.

API Reference

Search & Discovery

Query Construction

Extract 2-3 key terms from the question. Avoid natural language filler.

Question	Key Terms	Query
"code structure"	code, structure	`q=code+structure`
"Why was X chosen?"	why, chosen	`q=decision` (use DECISIONS.md)
"Any known issues?"	issues, bugs	`q=debt` (use DEBT.md)
"architecture documentation"	architecture	`q=architecture`

Default: 1-2 keywords from the question.

Use the search endpoint. Project is auto-detected from CWD.

# Search current project (default)
curl -s '$ALCOVE_URL/search?q=QUERY'

# Search with options
curl -s '$ALCOVE_URL/search?q=QUERY&limit=10&mode=hybrid'

# Search a specific project
curl -s '$ALCOVE_URL/search?q=QUERY&project=PROJ'

# Search across all projects
curl -s '$ALCOVE_URL/search?q=QUERY&limit=20'

# POST search (JSON body)
curl -s -X POST $ALCOVE_URL/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"q": "QUERY", "limit": 10, "project": "proj", "mode": "hybrid"}'

Response: {"query": "...", "results": [...], "mode": "...", "truncated": false}

Project Operations

# List projects
curl -s $ALCOVE_URL/projects

# Init project
curl -s -X POST $ALCOVE_URL/projects \
  -H 'Content-Type: application/json' \
  -d '{"project_name": "myproj", "project_path": "/abs/path"}'

# Project docs overview (with sizes and classification)
curl -s $ALCOVE_URL/projects/PROJECT/docs

# Audit doc health
curl -s $ALCOVE_URL/projects/PROJECT/audit

# Validate against policy.toml
curl -s $ALCOVE_URL/projects/PROJECT/validate

# Configure project settings
curl -s -X PUT $ALCOVE_URL/projects/PROJECT/config \
  -H 'Content-Type: application/json' \
  -d '{"core_files": ["PRD.md", "ARCHITECTURE.md"]}'

# Read a doc file
curl -s '$ALCOVE_URL/docs/PRD.md?project=PROJECT'
curl -s '$ALCOVE_URL/docs/reports/weekly.md?project=PROJECT&offset=0&limit=2000'

# Index code structure
curl -s -X POST $ALCOVE_URL/index-code \
  -H 'Content-Type: application/json' \
  -d '{"source_path": "/abs/path/src", "language": "rust", "project": "PROJECT"}'

Action	Method	Endpoint
List projects	GET	`/projects`
Init project	POST	`/projects`
Project docs overview	GET	`/projects/{name}/docs`
Audit project	GET	`/projects/{name}/audit`
Validate docs	GET	`/projects/{name}/validate`
Configure project	PUT	`/projects/{name}/config`
Read doc file	GET	`/docs/{path}?project=name`
Index code	POST	`/index-code`

Index & Maintenance

# Update index — incremental (changed/added/deleted files only), all projects
curl -s -X POST $ALCOVE_URL/index
# ↑ DEFAULT for "make new docs searchable" or "rebuild index"

# Update index — single project only
curl -s -X POST $ALCOVE_URL/projects/PROJECT/index
# ↑ ONLY when explicitly targeting a specific project

# Check changed files since last index
curl -s '$ALCOVE_URL/changes?auto_rebuild=true'

# Lint docs
curl -s '$ALCOVE_URL/lint?project=PROJECT'

Rule: Default to /index (global). Use /projects/{name}/index only when task specifies a single project.

Action	Method	Endpoint
Update index (all projects)	POST	`/index`
Update index (single project)	POST	`/projects/{name}/index`
Check changes	GET	`/changes?auto_rebuild=true`
Lint project	GET	`/lint?project=name`

Vault Operations

# List vaults
curl -s $ALCOVE_URL/vaults

# Search vaults
curl -s '$ALCOVE_URL/vaults/search?q=QUERY&vault=*&limit=20'

# Backup vault
curl -s -X POST $ALCOVE_URL/vaults/backup \
  -H 'Content-Type: application/json' \
  -d '{"vault_name": "myvault"}'

# Promote document into doc-repo
curl -s -X POST $ALCOVE_URL/promote \
  -H 'Content-Type: application/json' \
  -d '{"source": "/abs/path/notes.md", "project": "PROJECT", "copy": true}'

Action	Method	Endpoint
List vaults	GET	`/vaults`
Search vault	GET	`/vaults/search?q=...`
Backup vault	POST	`/vaults/backup`
Promote doc	POST	`/promote`

MCP Proxy (Legacy)

The JSON-RPC proxy remains available for MCP clients:

curl -s -X POST $ALCOVE_URL/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"TOOL_NAME","arguments":{}}}'

Health Check

curl -s $ALCOVE_URL/health
# → {"status": "ok", "version": "x.y.z", "docs_root_configured": true, "projects": N}

Rules

Scope

Default: current project. Ambiguous → ask. Global only on explicit request.

Before writing code

CONVENTIONS.md → project-specific rules
CODE_INDEX.md → compact module/type/function overview (avoids reading dozens of source files)
For research/reference material → search vaults via GET /vaults/search?q=...

Answering questions

Never answer from memory. Call GET /projects/{name}/docs → GET /docs/{path}?project=name for the relevant file → summarize. Do not dump full files unless asked.

Doc status disambiguation

User says	Endpoint
validate, policy, compliance	`GET /projects/{name}/validate`
lint, broken link, orphan, stale	`GET /lint?project=name`
audit, organize, cleanup, what's missing	`GET /projects/{name}/audit` (runs both validate + lint)
changed, stale index, new files	`GET /changes?auto_rebuild=true`

Ambiguous → call audit_project (broadest).

Acting on audit results

alcove → project repo: OK for public-facing docs derived from internal content
project repo → alcove: OK to restructure reference materials
Internal docs → project repo: NEVER expose PRD/ARCHITECTURE/etc.
Always confirm before moving/deleting files
Re-run validate + lint after cleanup

Promoting notes

Path provided → act immediately: POST /promote with the source path. No matching project → inbox/. Then POST /index.

After development

Proactively capture at natural stopping points:

Architecture change → ARCHITECTURE.md
Decision rationale → DECISIONS.md
Bug/workaround → DEBT.md
Coding pattern → CONVENTIONS.md
Env var → SECRETS_MAP.md
Progress → PROGRESS.md

Read → append with date → POST /index.