alcove

Alcove

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

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

Question	File
"What does this do?"	PRD.md
"How is this built?" / code structure	ARCHITECTURE.md / CODE_INDEX.md
"What's the status?"	PROGRESS.md
"Why was X chosen?"	DECISIONS.md
"What style to use?"	CONVENTIONS.md
"What env vars needed?"	SECRETS_MAP.md
"Any known issues?"	DEBT.md

Unsure → search via API. Never contradict existing decisions.

API Reference

Search & Discovery

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

# Update index — single project only
curl -s -X POST $ALCOVE_URL/projects/PROJECT/index

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

# Lint docs
curl -s '$ALCOVE_URL/lint?project=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

1. CONVENTIONS.md → project-specific rules
2. CODE_INDEX.md → compact module/type/function overview (avoids reading dozens of source files)
3. 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.