Make the W3DS agent skill authoritative and eVault-first by coodos · Pull Request #1125 · MetaState-Prototype-Project/prototype

coodos · 2026-08-31T13:41:24Z

Description of change

The W3DS agent skill (skills/w3ds/**) is what actually runs when someone builds a platform with Codex, Claude Code, Cursor or Copilot — so its blind spots become their architecture. It had three:

1. It cited an authority the reader does not have. Every reference was a repo-relative path (docs/docs/Post Platform Guide/mapping-rules.md) and the fallback instruction was grep -r docs/docs/. Neither exists for the target user: someone who ran npx skills add …@w3ds in their own project. When the skill was thin, the agent had nowhere to go, so it invented.

Every citation is now a live docs.w3ds.metastate.foundation URL, and SKILL.md opens with an Authority section: the docs site is authoritative, the skill is a condensed index of it, and where they disagree the docs win. A new Docusaurus plugin publishes /llms.txt, /llms-full.txt and the skill itself at /skill/**, so a fetch-capable agent can self-serve with nothing installed — and the manual Copilot / Windsurf / Codex installs become a single curl instead of hand-rolled concatenation.

2. It taught mechanics but never the philosophy. Mapping files, handleChange, webhook controllers — but nothing saying the eVault holds the truth and the platform DB is a projection. An agent following it faithfully builds a conventional app with sync bolted on: W3DS-flavoured, not W3DS-native.

New page Data Ownership Rules coins the rule and reconciles it with the existing canonical line that platforms are "caches and aggregators": that is permission to keep a fast copy of something authoritative elsewhere, never permission to own it. The decision procedure is the reconstructability test — if this database were dropped and rebuilt by replaying the relevant eVaults, what would be lost? A local DB is not a violation; a local DB that is the only home for some user data is. The page lists legitimate local-only state explicitly (sessions, queues, ID mappings, cached resolutions, derived indexes) so the rule stays applicable rather than absolutist, and does not start refusing the normal adapter work that pictique, blabsy and ecurrency already do.

3. It presented stale identifiers as canon.reference/registry.md said "Memorize this table" over 9 ontology UUIDs. services/ontology/schemas/ holds 37; production serves 32; GET /schemas is live. Real UUIDs also sat inside copy-pasteable mapping.json examples.

The table is gone. skills/ now contains zero ontology UUIDs — examples use "<the User schemaId, resolved from GET …/schemas>", which cannot be pasted as-is. In its place is a resolution procedure: /schemas → /domains/:id/schemas → /schemas/:id. w3ds-file-v1 stays verbatim and is labelled as what it is: a protocol string literal, not a registry lookup.

4. It never mentioned GitW3. The skill described eVaults, adapters and protocols, and said nothing about where the platform itself lives — so an agent would happily wire an application to any Git host and only discover the missing identity later, when retrofitting it is worst.

New reference/gitw3.md covers the forge as the second half of the same principle: the user's data belongs in their eVault, and the platform's identity belongs in its repository — .w3ds/platform.json beside the code, published from there. Ordinary Git hosting carries the code but not the platform eName, published profile, per-version identities, PPA certificates or deployment records. The skill now raises this early rather than after the fact, and knows the specifics that go wrong:

A plain repository import is not the guided port flow. If an existing platform identity must survive, the port stages the eName migration behind a wallet signature and leaves the old public listing in control until an administrator activates the cutover.
Managed manifest fields are off-limits.platformName, an assigned ename, the release-controlled version and any PPA proof field are written by GitW3. Never hand-edit, fabricate, or copy them between platforms.
PPA certifies one exact version. A certificate for 1.2.3 says nothing about 1.2.4, and only a published stable semantic release counts — not a draft, prerelease, or latest.
Deployment key handling.w3ds-deployment-key.json is downloaded once and unrecoverable; server-side only, from a secret manager or read-only mount, validated at startup, never committed, never shipped in a client bundle, never pasted into a prompt.
PP-Auth SDK integration is coming soon, so the skill leaves a narrow boundary instead of inventing a package name, endpoint or wire protocol to fill it.
Stop-and-ask conditions for repository work: auth failures, an unexpectedly non-empty destination, conflicting histories, an eName that would be replaced, an invalid manifest, a wallet that is not a profile author, or a push that would rewrite history. No force-push without the user's independent review.

What the skill now does differently

Pre-flight gate before writing any W3DS code: which ontology, whose eVault, truth or projection, what writes it to the eVault.
Two hard stops — stop and ask, rather than write code, when a design makes the local DB authoritative for user data, or when a persisted entity type has no ontology.
The second stop is a path, not a wall. Ontologies are ordinary JSON files anyone can PR, so the agent drafts the draft-07 schema and offers to open the PR instead of inventing a schemaId or giving up. Infrastructure/Ontology.md gains a Proposing a new ontology section documenting the real procedure, and the previously undocumented GET /domains and GET /domains/:id/schemas endpoints that make "does something already exist for this?" answerable.
No fetch capability is not a refusal. Offline or tool-less agents proceed, but must name every unverified identifier and mark it in code rather than substituting a plausible value — a wrong schemaId fails silently, which is worse than an obvious placeholder.
A definition of done: X-ENAME on every call, handleChange on every write path, idempotent webhook controller, no invented identifiers.

reference/w3ds-native.md (new) carries the reasoning behind those rules: the reconstructability test worked through real cases, and eight anti-patterns as wrong → right → why.

The install page was also orphaned — nothing in the docs, README.md or QUICKSTART.md linked to it. Now linked from Getting Started and the root README.

Issue Number

N/A

Type of change

Docs (changes to the documentation)
New (a change which implements a new feature) — the llms-txt Docusaurus plugin

How the change has been tested

pnpm --filter docs build succeeds. onBrokenLinks: 'throw' covers the sidebar_position renumber in W3DS Basics and every new cross-reference. (Pre-existing broken anchors in glossary.md / W3ID.md still warn; untouched, out of scope.)
Served the build and confirmed 200 on /llms.txt, /llms-full.txt, /skill/SKILL.md, /skill/reference/platform.md, /skill/reference/w3ds-native.md, /skill/reference/gitw3.md, /skill/w3ds-full.txt, plus the two new/edited doc pages.
llms.txt indexes 44 pages, matching find docs/docs -name '*.md' | wc -l.
No UUID matches anywhere under skills/. The only two remaining docs/docs mentions are deliberate prose.
Every intra-skill link and anchor resolves (script-checked) — this caught two stale anchors, one of them pre-existing.
All 42 distinct docs.w3ds.metastate.foundation URLs referenced from skills/ and docs/ resolve to a real page, anchors included.
Live endpoints confirm the documented shapes: GET /schemas carries domain, GET /domains returns {schemaId, domains}.

Not tested: the behavioural check (fresh agent, scratch project, three prompts — add an entity with no ontology, cache a display name, ask for the User ontology ID). Worth someone running before merge.

Noted for follow-up, not fixed here: production Ontology serves 32 schemas while the repo has 37, so the deployed service is behind. It is also the argument for resolving rather than recalling.

Change checklist

I have ensured that the CI Checks pass locally
I have removed any unnecessary logic
My code is well documented
I have signed my commits
My code follows the pattern of the application
I have self reviewed my code

…e an ontology

…kill

coderabbitai · 2026-08-31T13:41:32Z

Important

🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c0be0f1c-43a8-4506-b296-096e443cc594

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

…3 repository

coodos · 2026-08-31T13:41:24Z