diff --git a/packages/cli/skills/dkg-node/SKILL.md b/packages/cli/skills/dkg-node/SKILL.md index 61cd09814..fa416fcab 100644 --- a/packages/cli/skills/dkg-node/SKILL.md +++ b/packages/cli/skills/dkg-node/SKILL.md @@ -69,10 +69,10 @@ curl -X POST $BASE_URL/api/shared-memory/write \ **Step 3 — Publish to Verified Memory:** ```bash -curl -X POST $BASE_URL/api/publish \ +curl -X POST $BASE_URL/api/shared-memory/publish \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ - -d '{"contextGraphId": "my-context-graph", "quads": [...]}' + -d '{"contextGraphId": "my-context-graph"}' ``` **Step 4 — Query:** @@ -81,7 +81,7 @@ curl -X POST $BASE_URL/api/publish \ curl -X POST $BASE_URL/api/query \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ - -d '{"sparql": "SELECT * WHERE { ?s ?p ?o } LIMIT 10", "contextGraphId": "my-context-graph", "includeSharedMemory": true}' + -d '{"sparql": "SELECT * WHERE { ?s ?p ?o } LIMIT 10", "contextGraphId": "my-context-graph", "view": "shared-working-memory"}' ``` ## 4. Authentication @@ -111,7 +111,8 @@ The token is configured in the node's config file or provided at startup. ### Querying -- `POST /api/query` — SPARQL query with optional `view` (`working-memory`, `shared-working-memory`, `verified-memory`), `agentAddress`, `assertionName`, `verifiedGraph`, `subGraphName`, `includeSharedMemory`, `contextGraphId` parameters +- `POST /api/query` — SPARQL query with optional `contextGraphId`, `includeSharedMemory`, `view` (`working-memory`, `shared-working-memory`, `verified-memory`), `agentAddress`, `assertionName`, `verifiedGraph` parameters + - **Note:** `subGraphName` is supported for legacy routing only and cannot be combined with `view` - `POST /api/query-remote` — query a remote peer via P2P ### Working Memory (WM) — Private assertions (🚧 Planned) @@ -179,14 +180,19 @@ curl -X POST $BASE_URL/api/assertion/my-assertion/import-file \ | 502 | Chain/upstream error | Retry — transient blockchain issue | | 503 | Service unavailable | Node is starting up or shutting down | -## 10. Workflow Recipes +## 10. Common Workflows -For detailed step-by-step workflow recipes and the full endpoint reference, see -the supporting files in the skill directory: +**Write → Share → Publish:** -- `workflows.md` — 10 workflow recipes with curl examples -- `api-reference.md` — full endpoint reference grouped by workflow -- `examples/sparql-recipes.md` — SPARQL query patterns +1. Create a context graph (`POST /api/context-graph/create`) +2. Write triples to shared memory (`POST /api/shared-memory/write`) +3. Publish to verified memory (`POST /api/shared-memory/publish`) + +**Query across layers:** + +- Shared memory: `{"sparql": "...", "contextGraphId": "...", "view": "shared-working-memory"}` +- Verified memory: `{"sparql": "...", "contextGraphId": "...", "view": "verified-memory"}` +- Working memory (planned): `{"sparql": "...", "view": "working-memory", "agentAddress": "...", "contextGraphId": "..."}` ## Appendix: V9 → V10 Migration diff --git a/packages/cli/src/daemon.ts b/packages/cli/src/daemon.ts index 713cc7801..14b43dea3 100644 --- a/packages/cli/src/daemon.ts +++ b/packages/cli/src/daemon.ts @@ -107,7 +107,7 @@ function buildSkillMd(opts: { `- **Base URL:** ${opts.baseUrl}`, `- **Peer ID:** ${opts.peerId}`, `- **Node role:** ${opts.nodeRole}`, - `- **Available extraction pipelines:** ${opts.extractionPipelines.length > 0 ? opts.extractionPipelines.join(', ') : 'text/markdown'}`, + `- **Available extraction pipelines:** ${opts.extractionPipelines.length > 0 ? opts.extractionPipelines.join(', ') : 'none (install markitdown to enable document conversion)'}`, `- **Subscribed Context Graphs:** use \`GET /api/context-graph/list\` (requires auth)`, ].join('\n'); @@ -1227,7 +1227,7 @@ async function handleRequest( const proto = req.headers['x-forwarded-proto'] ?? 'http'; const host = req.headers['x-forwarded-host'] ?? req.headers.host ?? `localhost:${config.listenPort ?? 9200}`; const baseUrl = `${proto}://${host}`; - const pipelines = ['text/markdown', ...extractionRegistry.availableContentTypes()]; + const pipelines = extractionRegistry.availableContentTypes(); const content = buildSkillMd({ version: nodeVersion, baseUrl, @@ -1244,6 +1244,7 @@ async function handleRequest( 'Content-Type': 'text/markdown; charset=utf-8', 'ETag': etag, 'Cache-Control': 'public, max-age=300', + 'Vary': 'Host, X-Forwarded-Host, X-Forwarded-Proto', }); res.end(content); return; @@ -2116,7 +2117,7 @@ async function handleRequest( msg.startsWith('SPARQL rejected:') || msg.startsWith('Parse error') || /must start with (SELECT|CONSTRUCT|ASK|DESCRIBE)/i.test(msg) || msg.includes('was removed in V10') || - msg.includes('requires agentAddress') || msg.includes('requires contextGraphId') || + msg.includes('agentAddress is required') || msg.includes('requires a contextGraphId') || msg.includes('cannot be combined with') ) { return jsonResponse(res, 400, { error: msg }); diff --git a/packages/cli/test/skill-endpoint.test.ts b/packages/cli/test/skill-endpoint.test.ts index 21c20bfaa..f775abc5f 100644 --- a/packages/cli/test/skill-endpoint.test.ts +++ b/packages/cli/test/skill-endpoint.test.ts @@ -70,7 +70,7 @@ describe('SKILL.md file', () => { expect(skillContent).toContain('## 7. File Ingestion'); expect(skillContent).toContain('## 8. Node Administration'); expect(skillContent).toContain('## 9. Error Reference'); - expect(skillContent).toContain('## 10. Workflow Recipes'); + expect(skillContent).toContain('## 10. Common Workflows'); }); it('contains dynamic placeholders for node info', () => {