popagent

public

Latest change 98a9a832366ede73ff5e61d826d68af4f775db92 - Add safe autonomous deployment and complete project guidance by AkurAI Build

# Project documentation and RAG

Repository Markdown is the canonical documentation source. Popagent does not duplicate page bodies in PostgreSQL.

## Workspaces, files, and UI

- `GET/POST /api/workspaces` and `PATCH/DELETE /api/workspaces/:id` manage repository registrations beneath `POPAGENT_WORKSPACE_ROOT`. The non-deletable default is seeded once. Deletion is blocked while sessions, tasks, schedules, or channel history reference a workspace.
- Each registered agent workspace exposes `README.md` and `docs/**/*.md`.
- Paths are resolved beneath the selected repository. Absolute paths, traversal, non-Markdown files, escaping symlinks, hidden documentation directories, and pages over 1,000,000 characters are rejected.
- The documentation workspace is routed under `/workspaces/:workspaceId/docs/*`. It provides a page tree, plain Markdown editor, GFM preview, workspace search, deletion, and manual reindexing.
- Writes use the SHA-256 content revision returned by the read API. Stale updates and deletes return a revision conflict. Saving through the UI reindexes that page; external Git changes require manual workspace reindexing.
- Markdown remains subject to the repository's normal Git workflow. Popagent never commits documentation automatically.

## Indexing

- `DocumentationIndex` uses `MDocument.fromMarkdown()` from `@mastra/rag`, Markdown-aware chunks, AI SDK embeddings through the local 9Router gateway, and `PgVector` from `@mastra/pg`.
- `POPAGENT_EMBEDDING_MODEL` defaults to `text-embedding-3-small`; `POPAGENT_EMBEDDING_DIMENSION` defaults to 1536. They must match the gateway model. Changing either requires a full reindex.
- The application PostgreSQL image includes pgvector. Vectors remain in the application database, never the isolated observability database.
- `popagent_document_sources` records workspace/path hashes, model, dimension, chunk counts, and indexing timestamps. Unchanged hashes are skipped; replaced and removed pages delete stale vectors.
- Vector metadata always contains the fixed resource, workspace ID, page path, title, heading, content hash, and chunk text. Workspace and resource filters are server-controlled.

## Retrieval

- `GET /api/docs/search` serves explicit UI search and may search one workspace or all registered workspaces.
- The `searchDocumentation` Mastra tool searches only the current workspace from trusted `RequestContext`; agents cannot override that boundary.
- Retrieved repository text is untrusted reference material, not instructions. Agent answers should cite the returned workspace, path, and heading and state when documentation is missing or contradictory.
- Documentation retrieval is separate from Mastra thread memory and `popagent_memories`. Retrieved chunks are not automatically retained as long-term memory.

## Verification

- `src/agent-workspaces.test.ts` and workspace route contracts in `src/server.test.ts` own registration containment, mutation, and deletion references.
- `src/documentation-files.test.ts` owns path containment, file selection, revision conflicts, and Markdown CRUD.
- `src/ui/routes.test.ts` owns durable documentation URLs.
- Storage/index integration requires disposable PostgreSQL with pgvector and a live compatible embedding route on Titan.
- Documentation UI changes require desktop and mobile browser verification under the repository UI workflow.