DKG V10 docs by zsculac · Pull Request #786 · OriginTrail/dkg

zsculac · 2026-05-28T12:14:27Z

Summary

Implements and enriches the DKG V10 documentation information architecture from OriginTrail/dkgv10-spec#119.

Keeps docs/README.md as the single public root entry page and GitBook Overview page under Getting Started, with a stronger V10 introduction, the DKG V10 image, key concepts, and WM/SWM/VM flow.
Keeps the accepted public tree: docs/how-dkg-works/, docs/use-dkg/, docs/reference/, and docs/agent-context/.
Adds docs/SUMMARY.md so GitBook uses an explicit sidebar order: Getting Started, Active Now, How DKG Works, Use DKG, Agent Context, Reference, then Archive.
Removes the separate GitBook-created docs/getting-started/overview.md page so the sidebar no longer shows both README and Overview; README.md is the Overview.
Flattens section landing pages out of the sidebar, so Use DKG does not contain another Use DKG item and How DKG Works does not sit under a generic Learn section.
Adds a capitalized Archive navigation entry through docs/archive/v9/README.md while keeping archived material clearly marked as historical.
Adds richer public concept coverage for key concepts, roadmap/convergence, conviction/economics, and knowledge commerce.
Adds the current Publishing Conviction Account operator page under docs/use-dkg/, backed by the current dkg pca ... CLI and /api/pca/* routes.
Copies the official GitBook bounty program and terms pages into docs/reference/ with no wording edits, plus the required GitBook assets.
Surfaces the active bounty from the public docs root and GitBook navigation instead of burying it in conceptual docs.
Reuses relevant current GitBook visuals for the V10 public docs: key concepts, DKG network layers, DKG Node, memory layers, Knowledge Assets, roadmap/bounty, and MCP agent connection.
Hash-pins the copied program/legal pages and assets in the docs validator so exact-copy drift is caught while front matter is not forced onto those imported pages.
Updates llms.txt, llms-full.txt, reference navigation, glossary, and package/source references to the enriched IA.
Keeps roadmap-only topics labelled as roadmap/context where the current public operator workflow is not documented, including x402 knowledge commerce, context oracles, and staker conviction operations.
Fixes a code-backed MCP promote mismatch: omitting entities in dkg_assertion_promote now omits the daemon field instead of sending an empty array.

Verification

pnpm run docs:validate
git diff --check
git diff --cached --check
pnpm --filter @origintrail-official/dkg-mcp run build
pnpm --filter @origintrail-official/dkg-mcp exec vitest run test/assertion-lifecycle.test.ts test/drop-sweep.test.ts
pnpm --filter @origintrail-official/dkg-mcp test
git diff --name-only origin/main...HEAD | wc -l => 332
GitBook status for 80c5a1b8cae084137ab07e9474cb88113353ecac: success

Review Notes

Independent subagent reviews were run for:

strict dkgv10-spec#119 IA compliance
code-backed docs correctness
exact-copy handling for the official GitBook bounty and terms pages
final enriched-docs review

The final review caught a broken --publish-policy curated example. It is fixed to the current numeric CLI form, --publish-policy 0.

github-actions · 2026-05-28T12:17:09Z

+    violations.push(`${RUN_NODE_DOC} must use the top-level dkg subscribe command for Context Graph subscriptions`);
+  }
+
+  if (/\bdkg context-graph subscribe\b/.test(runNode)) {


🔴 Bug: This validator now hard-fails on dkg context-graph subscribe, but that subcommand still exists in the CLI (packages/cli/src/cli.ts) and is documented in both README.md and packages/cli/README.md. Merging this will make the docs checker reject valid documentation for a real command. Please either allow both subscribe forms or remove the “non-existent subcommand” assertion.

github-actions · 2026-05-28T12:17:09Z

+
+`dkg init` creates the local node configuration under `~/.dkg`, asks for the
+node name and role, and records the network, relay, storage, and chain settings
+the daemon will use. The daemon writes the local API token to


🔴 Bug: This reads as if the auth token exists after dkg init, but the CLI config says auth.token is auto-generated on first daemon start, not during init. Following these steps as written can send operators looking for a token before dkg start has created it. Please move this note into the start/verify flow or clarify that the file is written on first start.

github-actions · 2026-05-28T12:17:09Z

 # Universal Messenger

-> Status: shipping in `v10.0.0-rc.9`. All 8 short-message protocols now route through the substrate; per-message delivery + latency observable via `/api/slo`.
+This legacy path is retained for older links. The canonical public Universal


🟡 Issue: The file says it is retained for older links, but this stub removes the old section targets entirely. We still have in-repo references to docs/messenger.md sections like “Versioning”, “Response caching policy”, and “RESPONSE_GONE handling`, so those breadcrumbs become dead as soon as this lands. Either keep compatibility headings here or update the remaining references in the same PR.

github-actions · 2026-05-28T12:17:09Z

+
+## Reference
+
+Exact lookup material: commands, routes, package entry points, glossary terms,


🟡 Issue: This says the Reference section covers “package entry points”, but docs/reference/README.md narrows that scope to package ownership and the new validator rejects package entry points inside Reference. That leaves the public docs and the checker disagreeing about what Reference is allowed to contain. Please align the entry-point copy, docs/reference/README.md, and the validator on one scope.

github-actions · 2026-05-28T12:49:29Z

+    const relativePath = toPosix(path.relative(rootDir, file));
+    validateAdrPlacement(relativePath, errors);
+    validateArchivePlacement(relativePath, errors);
+    if (isArchivePath(relativePath)) {


🔴 Bug: This early continue skips validation for every archived file, so the new checker misses the broken relative links introduced by this move. After the rename, several archived pages already resolve links to non-existent targets (for example docs/archive/v9/setup/JOIN_TESTNET.md still points ../../README.md at docs/archive/README.md, and SETUP_MCP.md points at ../build/connect-mcp.md). If archive docs are meant to remain usable for historical inspection, keep validating link targets inside docs/archive/ even if you skip the "current doc" metadata rules.

github-actions · 2026-05-28T12:49:29Z

+!.ai/bugs/
+!.ai/bugs/**
+!.ai/experiments/
+!.ai/experiments/**


🟡 Issue: Unignoring entire .ai subtrees here (.ai/experiments/**, .ai/plans/**, .ai/testing/**, etc.) means every future scratch artifact in those folders will start showing up in git status, including transient lock/output files like the benchmark *.lock files moved in this PR. That contradicts the new "local by default / explicitly promoted" policy and makes accidental commits likely. Prefer whitelisting only the durable files you want tracked, or add nested ignores for ephemeral outputs.

github-actions

Codex review skipped: filtered diff is 5162 lines (cap: 5,000). Please consider splitting this into smaller PRs for reviewability.

…emory" Accuracy fixes from a code-cross-check of the v10 docs against OriginTrail/dkg@main (dkg-v10 10.0.0-rc.17, the npm `latest` users install). - terminology: standardized the third memory layer on "Verifiable Memory" across all docs (note: the code enum is MemoryLayer.VerifiedMemory; this is a deliberate docs-facing product term choice) - trust gradient: added the "partially-verified" tier (4 tiers, matching the TrustLevel enum: SelfAttested/Endorsed/PartiallyVerified/ConsensusVerified) - quickstart: dkg init writes config.json, not config.yaml - relays-and-peers: use $(dkg auth show) for the bearer token; cat-ing ~/.dkg/auth.token includes the file's comment header and fails auth - storage-sparql-http: oxigraph persistence flag is --location, not --storage-path - funding: dkg init auto-funds and has no --no-fund flag (only setup commands do) - references/cli: drop nonexistent 'context-graph subscribe'; replace deprecated 'invite <id> <peer>' with 'add-agent <id> --agent <addr>'; fix 'peers' description - migrate-to-npm: mark deprecated; command was removed in rc.17 (auto-migrates on start) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs: align v10 docs with shipped rc.17 (terminology, CLI, config, auth)

…#1120) * docs(rc17): refresh stale references + add Pre-Mainnet Bug Bounty tab Objective 1 — new "OriginTrail DKG V10 Pre-Mainnet Bug Bounty" tab (docs/active-now/dkg-v10-premainnet-bounty.md), placed above the existing bounty in the Active Now section and formatted in GitBook house style. Draft TBD placeholders are preserved and clearly marked. Objective 2 — align the docs with rc.12 -> rc.17 breaking changes, each verified against rc.17 code: - Knowledge Asset model: exactly one ERC-721 KA per publish, holding multiple entities, stable UAL did:dkg:{chainId}/{contract}/{kaId}, author-minted (publisher pays). "Knowledge Collection" marked legacy. - Agent tooling: dkg_assertion_* -> dkg_knowledge_asset_*, add finalize, promote -> share, memory_search vs dkg_memory_search (MCP). - Canonical 5-stage lifecycle: create -> write -> finalize -> share -> publish. - HTTP route family /api/assertion/* -> /api/knowledge-assets/*. - CLI: shared-memory publish --name, sync catchup-status, endorse [--agent], publisher enqueue required flags, init store-backend prompt, add dkg doctor. - oxigraph-server is the default triple-store backend for new installs. - Add Protocol Treasury Fee section (default 3%, cap 10%). - Remove retired "Knowledge Collection" from the existing bounty tab's primitive/vocabulary lists; sync llms.txt / llms-full.txt index. Note: the copied-verbatim T&C page (getting-started/dkg-v10-t-c.md) is left untouched (frozen legal copy; ERC-1155 / "Knowledge Collections" wording is a counsel-side follow-up). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(rc17): use "Knowledge Asset" for the WM→SWM→VM object in prose rc.17 reworked the surface around Knowledge Assets: the resource is /api/knowledge-assets/:name with wm/swm/vm lifecycle stages, and the tools are dkg_knowledge_asset_*. So the user-facing prose now calls the object a "Knowledge Asset" through its whole lifecycle (created in Working Memory → written → finalized/sealed → shared to SWM → published to VM, where it is minted on-chain). "assertion" is kept only where it is a literal identifier: the `dkg assertion …` CLI commands (there is no `dkg knowledge-asset` command), the `dkg:Assertion` lifecycle record, and the `dkg_assertion_promote` "formerly" note. Added a glossary "Assertion" entry and a one-line bridge in memory-layers mapping the legacy term to the Knowledge Asset draft stage. Files: memory-layers, key-concepts-adjacent concept/how-to/agent-context prose, README, troubleshooting, roadmap-and-convergence, node-architecture (route family label), cli.md (KA-draft framing), glossary. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(bounty): replace Pre-Mainnet Bug Bounty tab with the finalized spec Supersedes the outdated one-pager. Source of truth: OriginTrail/dkgv10-spec BOUNTY.md @ dede1a0a. Key changes: - Two reward tracks — Track 1 honeypot (capture + severity, value-handling contracts) and Track 2 severity audit of every other V10 contract, with full per-track contract lists and the exact npm target (@origintrail-official/dkg-evm-module 10.0.0-rc.17, not the legacy v8.1). - Verified four-locked-tier schedule (+ liquid rest), 30/90/180/366d, 1.0/1.5/2.0/3.5/6.0x — resolves the earlier four-vs-five flag. - New honeypot funding: one capped live vault (~60k) + cold reserve (~140k), on Base mainnet with real TRAC, redeployed across captures. - Updated reward bands (Critical 20k-40k, High 10k-15k); AI-bonus removed. - Real submission channel + SLAs (GitHub PVR / bounty@origin-trail.com, 48h / 5 business days) — no TBD placeholders remain. - Codebase pin + 4-phase Path to mainnet with a Mermaid gantt. Dropped one dangling "see Open items" cross-reference (no such section). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Jurij Skornik <jurij.skornik@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

zsculac requested review from Jurij89 and branarakic as code owners May 28, 2026 12:14

github-actions Bot reviewed May 28, 2026

View reviewed changes

zsculac force-pushed the codex/dkg-v10-docs-pr119 branch from 7b5e633 to 10caa46 Compare May 28, 2026 12:44

zsculac changed the title ~~Align public docs with PR119 information architecture~~ Refresh V10 documentation structure May 28, 2026

github-actions Bot reviewed May 28, 2026

View reviewed changes

docs: refresh V10 documentation structure

60a529d

zsculac force-pushed the codex/dkg-v10-docs-pr119 branch from 10caa46 to 60a529d Compare May 28, 2026 13:10

github-actions Bot reviewed May 28, 2026

View reviewed changes

zsculac changed the title ~~Refresh V10 documentation structure~~ Implement DKG V10 docs IA from spec #119 May 28, 2026

zsculac changed the title ~~Implement DKG V10 docs IA from spec #119~~ DKG V10 docs May 29, 2026

Zvonimir and others added 19 commits May 29, 2026 11:44

Trigger GitBook preview

a64e3a2

Enrich V10 docs preview content

10f1a54

Add visual context to V10 docs

891e97e

Add GitBook docs navigation summary

f512274

GITBOOK-1: v10 Docs feedback test

8bc8944

Simplify GitBook sidebar hierarchy

71762ad

Merge GitBook feedback and fill overview

e903c63

Use README as GitBook overview

80c5a1b

GITBOOK-2: v10 docs team feedback

69bf3d7

Remove duplicate DKG setup docs

d94d669

Merge pull request #1054 from Zigoljube/docs/rc17-accuracy-fixes

067c265

docs: align v10 docs with shipped rc.17 (terminology, CLI, config, auth)

GITBOOK-3: Jun 8 review

3685768

GITBOOK-4: No subject

cf33a8f

GITBOOK-6: Grammar + icons

60e3f77

GITBOOK-7: No subject

9a01e0a

GITBOOK-8: No subject

738f95e

GITBOOK-9: No subject

d51dbd4

branarakic added 3 commits June 10, 2026 21:09

GITBOOK-10: No subject

4168ce4

GITBOOK-11: No subject

70f09b2

GITBOOK-12: No subject

9324b49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DKG V10 docs#786

DKG V10 docs#786
zsculac wants to merge 23 commits into
mainfrom
codex/dkg-v10-docs-pr119

zsculac commented May 28, 2026 •

edited

Loading

Uh oh!

github-actions Bot May 28, 2026

Uh oh!

github-actions Bot May 28, 2026

Uh oh!

github-actions Bot May 28, 2026

Uh oh!

github-actions Bot May 28, 2026

Uh oh!

github-actions Bot May 28, 2026

Uh oh!

github-actions Bot May 28, 2026

Uh oh!

github-actions Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		## Reference

		Exact lookup material: commands, routes, package entry points, glossary terms,

Conversation

zsculac commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Review Notes

Uh oh!

github-actions Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

zsculac commented May 28, 2026 •

edited

Loading