> For the complete documentation index, see [llms.txt](https://mcp.conserver.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mcp.conserver.io/optimization/session_handoff_for_vault.md). # Session handoff for vault ## What was implemented (high level) * **Discovery-first read surfaces** for attachment and analysis categories across **MCP resources** and **REST**. * **Canonical rule**: `attachment.purpose` is spec-facing; `attachment.type` is **legacy compatibility only**. **`analysis.type`** unchanged. * **Query layer**: distinct values for attachment types, attachment purposes, analysis types (Supabase + Mongo); Supabase **persists and reads `attachment.purpose`**. * **Shared helpers**: `src/utils/read-surfaces.ts` (filter, tags extract, discovery value shaping). * **Docs**: REST + resources + README; **four system-instruction copy-pastes** in `docs/examples/system-instruction-assets.md`; **thread bootstrap** in `docs/optimization/thread-context-bootstrap.md`. ## URIs and REST (cheat sheet) **MCP discovery** * `vcon://v1/discovery/attachments/purposes` (preferred) * `vcon://v1/discovery/attachments/types` (legacy) * `vcon://v1/discovery/analysis/types` **MCP filtered reads** * `vcon://v1/vcons/{uuid}/attachments/purpose/{purpose}` (preferred) * `vcon://v1/vcons/{uuid}/attachments/type/{type}` (legacy) * `vcon://v1/vcons/{uuid}/analysis/type/{type}` **REST** * `GET /api/v1/discovery/attachments/purposes` * `GET /api/v1/discovery/attachments/types` * `GET /api/v1/discovery/analysis/types` * `GET /api/v1/vcons/:uuid/attachments?purpose=...` (preferred) * `GET /api/v1/vcons/:uuid/attachments?type=...` (legacy) * `GET /api/v1/vcons/:uuid/analysis?type=...` ## Key files | Area | Path | | ------------------------------- | ----------------------------------------------- | | MCP resource list + resolve | `src/resources/index.ts` | | REST discovery | `src/api/routes/discovery.ts` | | REST vCon reads | `src/api/routes/vcons.ts` | | Router mount | `src/api/rest-router.ts` | | Filters | `src/utils/read-surfaces.ts` | | Types | `src/types/vcon.ts` | | IVConQueries | `src/db/interfaces.ts` | | Supabase | `src/db/queries.ts` | | Mongo | `src/db/mongo-queries.ts` | | add\_attachment schema | `src/tools/vcon-crud.ts` | | Instruction assets (4 variants) | `docs/examples/system-instruction-assets.md` | | Optimization bootstrap | `docs/optimization/thread-context-bootstrap.md` | ## Tests touched / added * `tests/new-tools-resources.test.ts` * `tests/api/routes/discovery.test.ts` * `tests/api/routes/vcons.test.ts` * `tests/db-queries.test.ts` * `tests/api/helpers.ts` ## Commands that were green * `npm run build` * `npx vitest run` (targeted suites during work) * `npm run docs:build` ## Policy for agents (one line) Discover **attachment purposes** and **analysis types** first; read by **`purpose`** for attachments and **`type`** for analysis; use **`attachment.type` only for legacy data**; use **tags** only when data lives in tags. ## Next thread (optimization) — suggested focus * Performance of distinct-category queries at scale (SQL vs batch fallback). * Whether to add **write-path normalization** (`type` → `purpose`) on ingest. * Optional deprecation timeline for attachment-`type` discovery surfaces. ## Checkpoint 2026-05-13 — shape graph, capabilities, tests **Shipped in repo (local commit, not pushed)** * **OSS shape graph**: `src/types/vcon-shape-graph.ts`; `getVconShapeGraph()` on `IVConQueries` with Postgres materialization (SQL path + fallback) and Mongo implementation; optional co-occurrence edges where supported. * **Surfaces**: MCP resource `vcon://v1/graph/shape`; read tool `vcon_graph_shape`; `vcon_capabilities` lists the tool and a `shape_graph` block (resource URI, JSON schema id, short description). `describe_response_shape` includes `vcon_graph_shape`. * **Docs**: `docs/api/shape-graph-and-plugins.md` (default graph plus how proprietary graphs attach via plugins). * **Tests**: `tests/handlers/schema.test.ts` and `tests/tools/templates.test.ts` aligned to 0.4.0 and real handler responses (raw JSON Schema for `get_schema`, file body for TypeScript mode); registry and tool-category counts; resource tests for shape graph; stress read for `vcon://v1/graph/shape`. **Suggested next hardening pass** * Re-read SQL for `getVconShapeGraph` under tenant RLS and large corpora (timeouts, `exec_sql` availability). * Optional caching for shape graph (same Redis optional pattern as other queries). * Contract tests for `SHAPE_GRAPH_FAILED` and oversized payloads if you add strict byte limits later. *** *Copy this file into your vault, or keep it in-repo and `@` it from the optimization thread.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://mcp.conserver.io/optimization/session_handoff_for_vault.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.