Docs/ontology and registry

[coodos]

Description of change

Add docs for ontology and registry

Issue Number

closes#751

Type of change

• Docs (changes to the documentation)

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

Summary by CodeRabbit

Release Notes

• Documentation

  • Added comprehensive documentation for Ontology and Registry services
  • Added Links reference page with production service URLs
  • Enhanced cross-linking across documentation for improved navigation
  • Updated terminology for clarity and consistency

• Site Updates

  • Updated domain to docs.w3ds.metastate.foundation
  • Refreshed branding with W3DS logo
  • Improved navigation structure in footer and menu

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR comprehensively restructures documentation by adding new service pages (Registry, Ontology, Links), adding internal cross-links throughout existing documentation, updating terminology from UUID to W3ID-based references, and refreshing Docusaurus configuration with production URLs and branding changes.

Changes

Cohort / File(s)	Summary
New Infrastructure Documentation docs/docs/Infrastructure/Ontology.md, docs/docs/Infrastructure/Registry.md, docs/docs/W3DS Basics/Links.md	Introduces three new documentation files: Ontology describes JSON Schema registry and W3ID schema identifiers; Registry details service discovery, entropy generation, and key binding certificates; Links provides a reference table of production service URLs.
Cross-linked Infrastructure Pages docs/docs/Infrastructure/eVault.md, docs/docs/Infrastructure/Web3-Adapter.md, docs/docs/Infrastructure/eID-Wallet.md, docs/docs/Infrastructure/eVault-Key-Delegation.md, docs/docs/Getting Started/getting-started.md	Adds internal hyperlinks to related documentation, replaces UUID references with W3ID terminology, updates service descriptions to reference Registry and Ontology pages, and links key concepts (MetaEnvelope, Bearer tokens, key binding certificates).
Cross-linked W3DS Basics & Protocol Pages docs/docs/W3DS Basics/W3ID.md, docs/docs/W3DS Basics/getting-started.md, docs/docs/W3DS Protocol/Authentication.md, docs/docs/W3DS Protocol/Signing.md, docs/docs/W3DS Protocol/Signature-Formats.md, docs/docs/W3DS Protocol/Awareness-Protocol.md	Converts plain references to Markdown links for eVault, Registry, eID Wallet, and Ontology; updates session identifier terminology from UUID to cryptographically secure 128-bit session ID; standardizes namespace generation descriptions.
Cross-linked Post Platform Guide docs/docs/Post Platform Guide/getting-started.md, docs/docs/Post Platform Guide/mapping-rules.md, docs/docs/Post Platform Guide/webhook-controller.md	Adds links to Authentication, Signing, eVault, Registry, Ontology, and Web3 Adapter docs; updates schemaId references from UUID to W3ID format; expands References sections with linked resources.
Docusaurus Configuration & Navigation docs/docusaurus.config.ts, docs/src/pages/index.tsx, README.md	Updates production URL to https://docs.w3ds.metastate.foundation, changes favicon to W3DS logo, updates navbar label from "Tutorial" to "Docs", expands footer links to include W3DS Basics, Infrastructure, and Links; modifies home page redirect to respect baseUrl configuration and updates page metadata.
Category Navigation docs/docs/Getting Started/_category_.json, docs/docs/Post Platform Guide/_category_.json, docs/docs/W3DS Basics/_category_.json, docs/docs/W3DS Protocol/_category_.json	Removes generated-index link metadata from category configuration files while retaining position and label fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related issues

• [question] Registry documentation 🧐 #109: The new Registry.md documentation directly addresses protocol concerns by detailing endpoints (/resolve, /entropy, /.well-known/jwks.json) and cross-linking Registry behavior throughout the documentation.

Possibly related PRs

• docs: add infrastructure, protocol, and getting started docs #721: Overlapping documentation changes in Getting Started, eVault, eID-Wallet, Registry, and related infrastructure docs.
• Fix/dreamsync recommendations #691: Both PRs modify docs/src/pages/index.tsx for redirect logic and metadata updates.
• docs: add docs for key delegation and auth #720: Both PRs modify authentication and eVault-Key-Delegation documentation with cross-references and terminology updates.

Suggested reviewers

• xPathin
• sosweetham
• JulienAuvo

Poem

🐰 Hops through the docs with glee,
Cross-links now guide discovery,
W3IDs dance, no UUIDs here—
The Registry's mirror, crystal clear,
A foundation of knowledge, anchored and neat,
Documentation's heart, now complete! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Docs/ontology and registry' is concise and directly references the main additions (ontology and registry documentation), aligning with the substantial changes across multiple docs.
Description check	✅ Passed	The PR description follows the required template with all key sections: change description, issue number, type of change, and completed checklist items.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/ontology-and-registry

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/docs/Post Platform Guide/getting-started.md (1)

64-85: ⚠️ Potential issue | 🟠 Major

Fix the auth request body to use w3id as the user identifier (and drop the eVault URL).

The example shows w3id as an eVault URL and also includes ename. This conflicts with the signing/verification flow that identifies users by w3id (eName). Use w3id as the identifier and remove the redundant ename. Based on learnings, the correct parameter name is w3id for user identification.

✅ Suggested doc correction

-{- "ename": "@user.w3id",- "session": "abc123...",- "w3id": "https://evault.example.com/users/123",- "signature": "z..."-}+{+ "w3id": "@user.w3id",+ "session": "abc123...",+ "signature": "z..."+}

- const { ename, session, signature } = req.body;+ const { w3id, session, signature } = req.body;
// Verify signature using signature-validator ...
const verificationResult = await verifySignature({
- eName: ename,+ eName: w3id,
signature: signature,
payload: session,
registryBaseUrl: process.env.PUBLIC_REGISTRY_URL,
});
- const user = await this.userService.findUser(ename);+ const user = await this.userService.findUser(w3id);

Also applies to: 76-99

🤖 Fix all issues with AI agents

In `@docs/docs/Post` Platform Guide/mapping-rules.md:
- Line 16: The examples are inconsistent: the top example uses "schemaId":
"global_schema_w3id" while later examples use UUIDs; update the examples that
set "schemaId" (the example occurrences that currently use
"550e8400-e29b-41d4-a716-446655440000") to match the W3ID format used in the
basic structure, or alternatively add a short clarifying sentence after the
basic structure explaining that "schemaId" may be either a W3ID (e.g.,
"global_schema_w3id") or a UUID and show both example variants; locate and edit
the example blocks that define schemaId to ensure consistent formatting or add
the explanatory note.
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 28-29: The anchor link targeting fromGlobal is broken: update the
link target (currently pointing to /docs/Infrastructure/Web3-Adapter#fromGlobal)
by either adding a dedicated heading "fromGlobal" (e.g., create a `###
fromGlobal` section so the anchor exists) in the Web3-Adapter document where the
fromGlobal function is discussed, or change the reference to an existing,
specific section such as `#receiving-data-inbound` where fromGlobal is covered;
ensure the Markdown heading text matches the anchor slug so the link resolves.

🧹 Nitpick comments (2)

docs/docs/W3DS Protocol/Signature-Formats.md (1)

324-324: Consider clarifying "unique identifier" terminology.

The change from "Create a UUID v4 for the namespace identifier" to "Create a unique identifier for the namespace" makes the terminology more generic. While this provides flexibility, it may leave readers uncertain about what format to use.

Consider either:

1. Keeping the UUID v4 specificity if that's the expected format, or
2. Adding a brief note about acceptable formats (e.g., "such as a UUID v4")

📝 Optional clarification

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a unique identifier for the namespace (e.g., UUID v4)

or, if any unique identifier is acceptable:

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a globally unique identifier for the namespace (such as UUID v4 or similar)

Also applies to: 329-329

docs/docs/W3DS Protocol/Authentication.md (1)

91-101: Align the reference snippet with the “session ID” terminology.

The text avoids UUID wording, but the example still uses uuidv4() and session. Consider renaming to sessionId and using a generic cryptographically secure generator (or add a short note that UUIDv4 is an acceptable 128‑bit session ID). This keeps terminology consistent and reduces reader confusion.

💡 Possible doc tweak

- const session = uuidv4();- const offer = `w3ds://auth?redirect=${url}&session=${session}&platform=blabsy`;+ const sessionId = crypto.randomUUID(); // 128-bit session ID+ const offer = `w3ds://auth?redirect=${url}&session=${sessionId}&platform=blabsy`;

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 49-52: The docs configuration's editUrl is pointing to the wrong
repository; update the docs.editUrl string in docusaurus.config.ts to the
correct GitHub repository path for this project (replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.
In `@docs/src/pages/index.tsx`:
- Around line 11-14: Normalize siteConfig.baseUrl to always end with a trailing
slash and avoid history.push on the homepage to prevent back-button loops: in
the useEffect referencing siteConfig.baseUrl and history.push, compute a safe
baseUrl (ensure it defaults to '/' and appends a '/' if missing), only run the
redirect when the current location pathname is the root (so you don't redirect
from nested pages), and use history.replace instead of history.push to perform
the navigation to `${baseUrl}docs/Getting%20Started/getting-started`; update
references to useEffect, siteConfig.baseUrl, and history.replace/history.push
accordingly.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Edit URL points to the wrong repository.
This appears to target a different repo name, which will break “Edit this page” links.

🔧 Proposed fix

- editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',+ editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',

📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	docs: {
	sidebarPath: './sidebars.ts',
	// Please change this to your repo.
	// Remove this to remove the "edit this page" links.
	editUrl:
	'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
	editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',
	},
	docs: {
	sidebarPath: './sidebars.ts',
	editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',
	},

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 49 - 52, The docs configuration's
editUrl is pointing to the wrong repository; update the docs.editUrl string in
docusaurus.config.ts to the correct GitHub repository path for this project
(replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/docusaurus.yml:
- Line 4: The workflow currently triggers on pull_request which allows the
deploy job to run for PRs; modify the deploy job (named "deploy" in the
docusaurus.yml) to skip runs on PR events by adding a job-level condition such
as checking the event name or branch (e.g., add an if condition like
github.event_name != 'pull_request' or require github.ref == 'refs/heads/main'
&& github.event_name == 'push') so deploy only runs on real pushes to the
production branch; apply the same guard to the other affected deploy-related
jobs referenced around the block noted (lines 39-57) to prevent accidental PR
deployments.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 23-28: The projectName value in the Docusaurus config is
incorrect; update the projectName symbol in the configuration (currently set to
'metastate') to 'prototype' so deploy scripts that rely on projectName (e.g.,
the GIT_USER yarn deploy flow referenced in docs/README.md) will target the
correct GitHub repo; leave organizationName unchanged and run a quick deploy
dry-run to confirm settings.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash# Look for Docusaurus deploy / gh-pages usage and repo configurationecho"=== Searching for deploy references ==="
rg -n "docusaurus deploy|gh-pages|npm run deploy|yarn deploy|pnpm deploy" --max-count=20
echo -e "\n=== Checking package.json for deploy scripts ==="if [ -f"package.json" ];then
cat package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" package.json ||echo"No deploy scripts found"fiecho -e "\n=== Checking docs/package.json ==="if [ -f"docs/package.json" ];then
cat docs/package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" docs/package.json ||echo"No deploy scripts found"fiecho -e "\n=== GitHub workflows related to docs ==="if [ -d".github/workflows" ];then
find .github/workflows -name "*.yml" -o -name "*.yaml"| head -20
fiecho -e "\n=== Repository name from git config ==="
git config --get remote.origin.url ||echo"Not a git repo"

Repository: MetaState-Prototype-Project/prototype

Length of output: 1398

---

🏁 Script executed:

#!/bin/bash# Examine docusaurus.config.ts to see full contextecho"=== Full docusaurus.config.ts (first 50 lines) ==="
head -50 docs/docusaurus.config.ts
echo -e "\n=== Checking for baseUrl and deploying related config ==="
rg -n "baseUrl|organizationName|projectName|url:" docs/docusaurus.config.ts -A 1 -B 1

Repository: MetaState-Prototype-Project/prototype

Length of output: 1993

---

🏁 Script executed:

#!/bin/bash# Look for any GitHub Actions workflows that might handle docs deploymentecho"=== Looking for docs-related workflows ==="
find .github/workflows -type f \( -name "*.yml" -o -name "*.yaml"\)2>/dev/null |whileread file;doecho"File: $file"if grep -q "docs\|docusaurus\|gh-pages""$file";thenecho"--- Content ---"
cat "$file"echo""fidone

Repository: MetaState-Prototype-Project/prototype

Length of output: 1817

---

Update projectName to match the actual repository name.

Line 28 sets projectName to 'metastate', but the repository is prototype. While the GitHub workflow bypasses docusaurus deploy and uses GitHub Pages directly, the docs/README.md instructs users to run GIT_USER=<username> yarn deploy, which relies on these settings. Running the deploy script would attempt to push to the wrong repository. Change projectName to 'prototype'.

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 23 - 28, The projectName value in the
Docusaurus config is incorrect; update the projectName symbol in the
configuration (currently set to 'metastate') to 'prototype' so deploy scripts
that rely on projectName (e.g., the GIT_USER yarn deploy flow referenced in
docs/README.md) will target the correct GitHub repo; leave organizationName
unchanged and run a quick deploy dry-run to confirm settings.

[nsergey82]

would be really nice if we had at least one example of each type somewhere. E.g., I have no idea from the top of my head how a "ledger" meta envelope may look like

[coodos]

@nsergey82 for these examples I imagine the better place would be the ontology viewer and not the docs, as then the docs may start to get more bloated.

[nsergey82]

not any w3ids, just the ename (according to out definitions)?

[nsergey82]

does it actually verify tokens, or merely provide us with material needed for such verification on our side?

[nsergey82]

this is obviously one of the candidates for pagination, but also rate limiting

[coodos]

pagination for this is being added

[coodos]

Description of change

Add docs for ontology and registry

Issue Number

closes#751

Type of change

• Docs (changes to the documentation)

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

Summary by CodeRabbit

Release Notes

• Documentation

  • Added comprehensive documentation for Ontology and Registry services
  • Added Links reference page with production service URLs
  • Enhanced cross-linking across documentation for improved navigation
  • Updated terminology for clarity and consistency

• Site Updates

  • Updated domain to docs.w3ds.metastate.foundation
  • Refreshed branding with W3DS logo
  • Improved navigation structure in footer and menu

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR comprehensively restructures documentation by adding new service pages (Registry, Ontology, Links), adding internal cross-links throughout existing documentation, updating terminology from UUID to W3ID-based references, and refreshing Docusaurus configuration with production URLs and branding changes.

Changes

Cohort / File(s)	Summary
New Infrastructure Documentation docs/docs/Infrastructure/Ontology.md, docs/docs/Infrastructure/Registry.md, docs/docs/W3DS Basics/Links.md	Introduces three new documentation files: Ontology describes JSON Schema registry and W3ID schema identifiers; Registry details service discovery, entropy generation, and key binding certificates; Links provides a reference table of production service URLs.
Cross-linked Infrastructure Pages docs/docs/Infrastructure/eVault.md, docs/docs/Infrastructure/Web3-Adapter.md, docs/docs/Infrastructure/eID-Wallet.md, docs/docs/Infrastructure/eVault-Key-Delegation.md, docs/docs/Getting Started/getting-started.md	Adds internal hyperlinks to related documentation, replaces UUID references with W3ID terminology, updates service descriptions to reference Registry and Ontology pages, and links key concepts (MetaEnvelope, Bearer tokens, key binding certificates).
Cross-linked W3DS Basics & Protocol Pages docs/docs/W3DS Basics/W3ID.md, docs/docs/W3DS Basics/getting-started.md, docs/docs/W3DS Protocol/Authentication.md, docs/docs/W3DS Protocol/Signing.md, docs/docs/W3DS Protocol/Signature-Formats.md, docs/docs/W3DS Protocol/Awareness-Protocol.md	Converts plain references to Markdown links for eVault, Registry, eID Wallet, and Ontology; updates session identifier terminology from UUID to cryptographically secure 128-bit session ID; standardizes namespace generation descriptions.
Cross-linked Post Platform Guide docs/docs/Post Platform Guide/getting-started.md, docs/docs/Post Platform Guide/mapping-rules.md, docs/docs/Post Platform Guide/webhook-controller.md	Adds links to Authentication, Signing, eVault, Registry, Ontology, and Web3 Adapter docs; updates schemaId references from UUID to W3ID format; expands References sections with linked resources.
Docusaurus Configuration & Navigation docs/docusaurus.config.ts, docs/src/pages/index.tsx, README.md	Updates production URL to https://docs.w3ds.metastate.foundation, changes favicon to W3DS logo, updates navbar label from "Tutorial" to "Docs", expands footer links to include W3DS Basics, Infrastructure, and Links; modifies home page redirect to respect baseUrl configuration and updates page metadata.
Category Navigation docs/docs/Getting Started/_category_.json, docs/docs/Post Platform Guide/_category_.json, docs/docs/W3DS Basics/_category_.json, docs/docs/W3DS Protocol/_category_.json	Removes generated-index link metadata from category configuration files while retaining position and label fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related issues

• [question] Registry documentation 🧐 #109: The new Registry.md documentation directly addresses protocol concerns by detailing endpoints (/resolve, /entropy, /.well-known/jwks.json) and cross-linking Registry behavior throughout the documentation.

Possibly related PRs

• docs: add infrastructure, protocol, and getting started docs #721: Overlapping documentation changes in Getting Started, eVault, eID-Wallet, Registry, and related infrastructure docs.
• Fix/dreamsync recommendations #691: Both PRs modify docs/src/pages/index.tsx for redirect logic and metadata updates.
• docs: add docs for key delegation and auth #720: Both PRs modify authentication and eVault-Key-Delegation documentation with cross-references and terminology updates.

Suggested reviewers

• xPathin
• sosweetham
• JulienAuvo

Poem

🐰 Hops through the docs with glee,
Cross-links now guide discovery,
W3IDs dance, no UUIDs here—
The Registry's mirror, crystal clear,
A foundation of knowledge, anchored and neat,
Documentation's heart, now complete! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Docs/ontology and registry' is concise and directly references the main additions (ontology and registry documentation), aligning with the substantial changes across multiple docs.
Description check	✅ Passed	The PR description follows the required template with all key sections: change description, issue number, type of change, and completed checklist items.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/ontology-and-registry

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/docs/Post Platform Guide/getting-started.md (1)

64-85: ⚠️ Potential issue | 🟠 Major

Fix the auth request body to use w3id as the user identifier (and drop the eVault URL).

The example shows w3id as an eVault URL and also includes ename. This conflicts with the signing/verification flow that identifies users by w3id (eName). Use w3id as the identifier and remove the redundant ename. Based on learnings, the correct parameter name is w3id for user identification.

✅ Suggested doc correction

-{- "ename": "@user.w3id",- "session": "abc123...",- "w3id": "https://evault.example.com/users/123",- "signature": "z..."-}+{+ "w3id": "@user.w3id",+ "session": "abc123...",+ "signature": "z..."+}

- const { ename, session, signature } = req.body;+ const { w3id, session, signature } = req.body;
// Verify signature using signature-validator ...
const verificationResult = await verifySignature({
- eName: ename,+ eName: w3id,
signature: signature,
payload: session,
registryBaseUrl: process.env.PUBLIC_REGISTRY_URL,
});
- const user = await this.userService.findUser(ename);+ const user = await this.userService.findUser(w3id);

Also applies to: 76-99

🤖 Fix all issues with AI agents

In `@docs/docs/Post` Platform Guide/mapping-rules.md:
- Line 16: The examples are inconsistent: the top example uses "schemaId":
"global_schema_w3id" while later examples use UUIDs; update the examples that
set "schemaId" (the example occurrences that currently use
"550e8400-e29b-41d4-a716-446655440000") to match the W3ID format used in the
basic structure, or alternatively add a short clarifying sentence after the
basic structure explaining that "schemaId" may be either a W3ID (e.g.,
"global_schema_w3id") or a UUID and show both example variants; locate and edit
the example blocks that define schemaId to ensure consistent formatting or add
the explanatory note.
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 28-29: The anchor link targeting fromGlobal is broken: update the
link target (currently pointing to /docs/Infrastructure/Web3-Adapter#fromGlobal)
by either adding a dedicated heading "fromGlobal" (e.g., create a `###
fromGlobal` section so the anchor exists) in the Web3-Adapter document where the
fromGlobal function is discussed, or change the reference to an existing,
specific section such as `#receiving-data-inbound` where fromGlobal is covered;
ensure the Markdown heading text matches the anchor slug so the link resolves.

🧹 Nitpick comments (2)

docs/docs/W3DS Protocol/Signature-Formats.md (1)

324-324: Consider clarifying "unique identifier" terminology.

The change from "Create a UUID v4 for the namespace identifier" to "Create a unique identifier for the namespace" makes the terminology more generic. While this provides flexibility, it may leave readers uncertain about what format to use.

Consider either:

1. Keeping the UUID v4 specificity if that's the expected format, or
2. Adding a brief note about acceptable formats (e.g., "such as a UUID v4")

📝 Optional clarification

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a unique identifier for the namespace (e.g., UUID v4)

or, if any unique identifier is acceptable:

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a globally unique identifier for the namespace (such as UUID v4 or similar)

Also applies to: 329-329

docs/docs/W3DS Protocol/Authentication.md (1)

91-101: Align the reference snippet with the “session ID” terminology.

The text avoids UUID wording, but the example still uses uuidv4() and session. Consider renaming to sessionId and using a generic cryptographically secure generator (or add a short note that UUIDv4 is an acceptable 128‑bit session ID). This keeps terminology consistent and reduces reader confusion.

💡 Possible doc tweak

- const session = uuidv4();- const offer = `w3ds://auth?redirect=${url}&session=${session}&platform=blabsy`;+ const sessionId = crypto.randomUUID(); // 128-bit session ID+ const offer = `w3ds://auth?redirect=${url}&session=${sessionId}&platform=blabsy`;

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 49-52: The docs configuration's editUrl is pointing to the wrong
repository; update the docs.editUrl string in docusaurus.config.ts to the
correct GitHub repository path for this project (replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.
In `@docs/src/pages/index.tsx`:
- Around line 11-14: Normalize siteConfig.baseUrl to always end with a trailing
slash and avoid history.push on the homepage to prevent back-button loops: in
the useEffect referencing siteConfig.baseUrl and history.push, compute a safe
baseUrl (ensure it defaults to '/' and appends a '/' if missing), only run the
redirect when the current location pathname is the root (so you don't redirect
from nested pages), and use history.replace instead of history.push to perform
the navigation to `${baseUrl}docs/Getting%20Started/getting-started`; update
references to useEffect, siteConfig.baseUrl, and history.replace/history.push
accordingly.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Edit URL points to the wrong repository.
This appears to target a different repo name, which will break “Edit this page” links.

🔧 Proposed fix

- editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',+ editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',

📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	docs: {
	sidebarPath: './sidebars.ts',
	// Please change this to your repo.
	// Remove this to remove the "edit this page" links.
	editUrl:
	'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
	editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',
	},
	docs: {
	sidebarPath: './sidebars.ts',
	editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',
	},

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 49 - 52, The docs configuration's
editUrl is pointing to the wrong repository; update the docs.editUrl string in
docusaurus.config.ts to the correct GitHub repository path for this project
(replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/docusaurus.yml:
- Line 4: The workflow currently triggers on pull_request which allows the
deploy job to run for PRs; modify the deploy job (named "deploy" in the
docusaurus.yml) to skip runs on PR events by adding a job-level condition such
as checking the event name or branch (e.g., add an if condition like
github.event_name != 'pull_request' or require github.ref == 'refs/heads/main'
&& github.event_name == 'push') so deploy only runs on real pushes to the
production branch; apply the same guard to the other affected deploy-related
jobs referenced around the block noted (lines 39-57) to prevent accidental PR
deployments.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 23-28: The projectName value in the Docusaurus config is
incorrect; update the projectName symbol in the configuration (currently set to
'metastate') to 'prototype' so deploy scripts that rely on projectName (e.g.,
the GIT_USER yarn deploy flow referenced in docs/README.md) will target the
correct GitHub repo; leave organizationName unchanged and run a quick deploy
dry-run to confirm settings.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash# Look for Docusaurus deploy / gh-pages usage and repo configurationecho"=== Searching for deploy references ==="
rg -n "docusaurus deploy|gh-pages|npm run deploy|yarn deploy|pnpm deploy" --max-count=20
echo -e "\n=== Checking package.json for deploy scripts ==="if [ -f"package.json" ];then
cat package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" package.json ||echo"No deploy scripts found"fiecho -e "\n=== Checking docs/package.json ==="if [ -f"docs/package.json" ];then
cat docs/package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" docs/package.json ||echo"No deploy scripts found"fiecho -e "\n=== GitHub workflows related to docs ==="if [ -d".github/workflows" ];then
find .github/workflows -name "*.yml" -o -name "*.yaml"| head -20
fiecho -e "\n=== Repository name from git config ==="
git config --get remote.origin.url ||echo"Not a git repo"

Repository: MetaState-Prototype-Project/prototype

Length of output: 1398

---

🏁 Script executed:

#!/bin/bash# Examine docusaurus.config.ts to see full contextecho"=== Full docusaurus.config.ts (first 50 lines) ==="
head -50 docs/docusaurus.config.ts
echo -e "\n=== Checking for baseUrl and deploying related config ==="
rg -n "baseUrl|organizationName|projectName|url:" docs/docusaurus.config.ts -A 1 -B 1

Repository: MetaState-Prototype-Project/prototype

Length of output: 1993

---

🏁 Script executed:

#!/bin/bash# Look for any GitHub Actions workflows that might handle docs deploymentecho"=== Looking for docs-related workflows ==="
find .github/workflows -type f \( -name "*.yml" -o -name "*.yaml"\)2>/dev/null |whileread file;doecho"File: $file"if grep -q "docs\|docusaurus\|gh-pages""$file";thenecho"--- Content ---"
cat "$file"echo""fidone

Repository: MetaState-Prototype-Project/prototype

Length of output: 1817

---

Update projectName to match the actual repository name.

Line 28 sets projectName to 'metastate', but the repository is prototype. While the GitHub workflow bypasses docusaurus deploy and uses GitHub Pages directly, the docs/README.md instructs users to run GIT_USER=<username> yarn deploy, which relies on these settings. Running the deploy script would attempt to push to the wrong repository. Change projectName to 'prototype'.

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 23 - 28, The projectName value in the
Docusaurus config is incorrect; update the projectName symbol in the
configuration (currently set to 'metastate') to 'prototype' so deploy scripts
that rely on projectName (e.g., the GIT_USER yarn deploy flow referenced in
docs/README.md) will target the correct GitHub repo; leave organizationName
unchanged and run a quick deploy dry-run to confirm settings.

[nsergey82]

would be really nice if we had at least one example of each type somewhere. E.g., I have no idea from the top of my head how a "ledger" meta envelope may look like

[coodos]

@nsergey82 for these examples I imagine the better place would be the ontology viewer and not the docs, as then the docs may start to get more bloated.

[nsergey82]

not any w3ids, just the ename (according to out definitions)?

[nsergey82]

does it actually verify tokens, or merely provide us with material needed for such verification on our side?

[nsergey82]

this is obviously one of the candidates for pagination, but also rate limiting

[coodos]

pagination for this is being added

[coodos]

Description of change

Add docs for ontology and registry

Issue Number

closes#751

Type of change

• Docs (changes to the documentation)

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

Summary by CodeRabbit

Release Notes

• Documentation

  • Added comprehensive documentation for Ontology and Registry services
  • Added Links reference page with production service URLs
  • Enhanced cross-linking across documentation for improved navigation
  • Updated terminology for clarity and consistency

• Site Updates

  • Updated domain to docs.w3ds.metastate.foundation
  • Refreshed branding with W3DS logo
  • Improved navigation structure in footer and menu

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR comprehensively restructures documentation by adding new service pages (Registry, Ontology, Links), adding internal cross-links throughout existing documentation, updating terminology from UUID to W3ID-based references, and refreshing Docusaurus configuration with production URLs and branding changes.

Changes

Cohort / File(s)	Summary
New Infrastructure Documentation docs/docs/Infrastructure/Ontology.md, docs/docs/Infrastructure/Registry.md, docs/docs/W3DS Basics/Links.md	Introduces three new documentation files: Ontology describes JSON Schema registry and W3ID schema identifiers; Registry details service discovery, entropy generation, and key binding certificates; Links provides a reference table of production service URLs.
Cross-linked Infrastructure Pages docs/docs/Infrastructure/eVault.md, docs/docs/Infrastructure/Web3-Adapter.md, docs/docs/Infrastructure/eID-Wallet.md, docs/docs/Infrastructure/eVault-Key-Delegation.md, docs/docs/Getting Started/getting-started.md	Adds internal hyperlinks to related documentation, replaces UUID references with W3ID terminology, updates service descriptions to reference Registry and Ontology pages, and links key concepts (MetaEnvelope, Bearer tokens, key binding certificates).
Cross-linked W3DS Basics & Protocol Pages docs/docs/W3DS Basics/W3ID.md, docs/docs/W3DS Basics/getting-started.md, docs/docs/W3DS Protocol/Authentication.md, docs/docs/W3DS Protocol/Signing.md, docs/docs/W3DS Protocol/Signature-Formats.md, docs/docs/W3DS Protocol/Awareness-Protocol.md	Converts plain references to Markdown links for eVault, Registry, eID Wallet, and Ontology; updates session identifier terminology from UUID to cryptographically secure 128-bit session ID; standardizes namespace generation descriptions.
Cross-linked Post Platform Guide docs/docs/Post Platform Guide/getting-started.md, docs/docs/Post Platform Guide/mapping-rules.md, docs/docs/Post Platform Guide/webhook-controller.md	Adds links to Authentication, Signing, eVault, Registry, Ontology, and Web3 Adapter docs; updates schemaId references from UUID to W3ID format; expands References sections with linked resources.
Docusaurus Configuration & Navigation docs/docusaurus.config.ts, docs/src/pages/index.tsx, README.md	Updates production URL to https://docs.w3ds.metastate.foundation, changes favicon to W3DS logo, updates navbar label from "Tutorial" to "Docs", expands footer links to include W3DS Basics, Infrastructure, and Links; modifies home page redirect to respect baseUrl configuration and updates page metadata.
Category Navigation docs/docs/Getting Started/_category_.json, docs/docs/Post Platform Guide/_category_.json, docs/docs/W3DS Basics/_category_.json, docs/docs/W3DS Protocol/_category_.json	Removes generated-index link metadata from category configuration files while retaining position and label fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related issues

• [question] Registry documentation 🧐 #109: The new Registry.md documentation directly addresses protocol concerns by detailing endpoints (/resolve, /entropy, /.well-known/jwks.json) and cross-linking Registry behavior throughout the documentation.

Possibly related PRs

• docs: add infrastructure, protocol, and getting started docs #721: Overlapping documentation changes in Getting Started, eVault, eID-Wallet, Registry, and related infrastructure docs.
• Fix/dreamsync recommendations #691: Both PRs modify docs/src/pages/index.tsx for redirect logic and metadata updates.
• docs: add docs for key delegation and auth #720: Both PRs modify authentication and eVault-Key-Delegation documentation with cross-references and terminology updates.

Suggested reviewers

• xPathin
• sosweetham
• JulienAuvo

Poem

🐰 Hops through the docs with glee,
Cross-links now guide discovery,
W3IDs dance, no UUIDs here—
The Registry's mirror, crystal clear,
A foundation of knowledge, anchored and neat,
Documentation's heart, now complete! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Docs/ontology and registry' is concise and directly references the main additions (ontology and registry documentation), aligning with the substantial changes across multiple docs.
Description check	✅ Passed	The PR description follows the required template with all key sections: change description, issue number, type of change, and completed checklist items.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/ontology-and-registry

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/docs/Post Platform Guide/getting-started.md (1)

64-85: ⚠️ Potential issue | 🟠 Major

Fix the auth request body to use w3id as the user identifier (and drop the eVault URL).

The example shows w3id as an eVault URL and also includes ename. This conflicts with the signing/verification flow that identifies users by w3id (eName). Use w3id as the identifier and remove the redundant ename. Based on learnings, the correct parameter name is w3id for user identification.

✅ Suggested doc correction

-{- "ename": "@user.w3id",- "session": "abc123...",- "w3id": "https://evault.example.com/users/123",- "signature": "z..."-}+{+ "w3id": "@user.w3id",+ "session": "abc123...",+ "signature": "z..."+}

- const { ename, session, signature } = req.body;+ const { w3id, session, signature } = req.body;
// Verify signature using signature-validator ...
const verificationResult = await verifySignature({
- eName: ename,+ eName: w3id,
signature: signature,
payload: session,
registryBaseUrl: process.env.PUBLIC_REGISTRY_URL,
});
- const user = await this.userService.findUser(ename);+ const user = await this.userService.findUser(w3id);

Also applies to: 76-99

🤖 Fix all issues with AI agents

In `@docs/docs/Post` Platform Guide/mapping-rules.md:
- Line 16: The examples are inconsistent: the top example uses "schemaId":
"global_schema_w3id" while later examples use UUIDs; update the examples that
set "schemaId" (the example occurrences that currently use
"550e8400-e29b-41d4-a716-446655440000") to match the W3ID format used in the
basic structure, or alternatively add a short clarifying sentence after the
basic structure explaining that "schemaId" may be either a W3ID (e.g.,
"global_schema_w3id") or a UUID and show both example variants; locate and edit
the example blocks that define schemaId to ensure consistent formatting or add
the explanatory note.
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 28-29: The anchor link targeting fromGlobal is broken: update the
link target (currently pointing to /docs/Infrastructure/Web3-Adapter#fromGlobal)
by either adding a dedicated heading "fromGlobal" (e.g., create a `###
fromGlobal` section so the anchor exists) in the Web3-Adapter document where the
fromGlobal function is discussed, or change the reference to an existing,
specific section such as `#receiving-data-inbound` where fromGlobal is covered;
ensure the Markdown heading text matches the anchor slug so the link resolves.

🧹 Nitpick comments (2)

docs/docs/W3DS Protocol/Signature-Formats.md (1)

324-324: Consider clarifying "unique identifier" terminology.

The change from "Create a UUID v4 for the namespace identifier" to "Create a unique identifier for the namespace" makes the terminology more generic. While this provides flexibility, it may leave readers uncertain about what format to use.

Consider either:

1. Keeping the UUID v4 specificity if that's the expected format, or
2. Adding a brief note about acceptable formats (e.g., "such as a UUID v4")

📝 Optional clarification

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a unique identifier for the namespace (e.g., UUID v4)

or, if any unique identifier is acceptable:

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a globally unique identifier for the namespace (such as UUID v4 or similar)

Also applies to: 329-329

docs/docs/W3DS Protocol/Authentication.md (1)

91-101: Align the reference snippet with the “session ID” terminology.

The text avoids UUID wording, but the example still uses uuidv4() and session. Consider renaming to sessionId and using a generic cryptographically secure generator (or add a short note that UUIDv4 is an acceptable 128‑bit session ID). This keeps terminology consistent and reduces reader confusion.

💡 Possible doc tweak

- const session = uuidv4();- const offer = `w3ds://auth?redirect=${url}&session=${session}&platform=blabsy`;+ const sessionId = crypto.randomUUID(); // 128-bit session ID+ const offer = `w3ds://auth?redirect=${url}&session=${sessionId}&platform=blabsy`;

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 49-52: The docs configuration's editUrl is pointing to the wrong
repository; update the docs.editUrl string in docusaurus.config.ts to the
correct GitHub repository path for this project (replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.
In `@docs/src/pages/index.tsx`:
- Around line 11-14: Normalize siteConfig.baseUrl to always end with a trailing
slash and avoid history.push on the homepage to prevent back-button loops: in
the useEffect referencing siteConfig.baseUrl and history.push, compute a safe
baseUrl (ensure it defaults to '/' and appends a '/' if missing), only run the
redirect when the current location pathname is the root (so you don't redirect
from nested pages), and use history.replace instead of history.push to perform
the navigation to `${baseUrl}docs/Getting%20Started/getting-started`; update
references to useEffect, siteConfig.baseUrl, and history.replace/history.push
accordingly.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Edit URL points to the wrong repository.
This appears to target a different repo name, which will break “Edit this page” links.

🔧 Proposed fix

- editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',+ editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',

📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	docs: {
	sidebarPath: './sidebars.ts',
	// Please change this to your repo.
	// Remove this to remove the "edit this page" links.
	editUrl:
	'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
	editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',
	},
	docs: {
	sidebarPath: './sidebars.ts',
	editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',
	},

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 49 - 52, The docs configuration's
editUrl is pointing to the wrong repository; update the docs.editUrl string in
docusaurus.config.ts to the correct GitHub repository path for this project
(replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/docusaurus.yml:
- Line 4: The workflow currently triggers on pull_request which allows the
deploy job to run for PRs; modify the deploy job (named "deploy" in the
docusaurus.yml) to skip runs on PR events by adding a job-level condition such
as checking the event name or branch (e.g., add an if condition like
github.event_name != 'pull_request' or require github.ref == 'refs/heads/main'
&& github.event_name == 'push') so deploy only runs on real pushes to the
production branch; apply the same guard to the other affected deploy-related
jobs referenced around the block noted (lines 39-57) to prevent accidental PR
deployments.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 23-28: The projectName value in the Docusaurus config is
incorrect; update the projectName symbol in the configuration (currently set to
'metastate') to 'prototype' so deploy scripts that rely on projectName (e.g.,
the GIT_USER yarn deploy flow referenced in docs/README.md) will target the
correct GitHub repo; leave organizationName unchanged and run a quick deploy
dry-run to confirm settings.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash# Look for Docusaurus deploy / gh-pages usage and repo configurationecho"=== Searching for deploy references ==="
rg -n "docusaurus deploy|gh-pages|npm run deploy|yarn deploy|pnpm deploy" --max-count=20
echo -e "\n=== Checking package.json for deploy scripts ==="if [ -f"package.json" ];then
cat package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" package.json ||echo"No deploy scripts found"fiecho -e "\n=== Checking docs/package.json ==="if [ -f"docs/package.json" ];then
cat docs/package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" docs/package.json ||echo"No deploy scripts found"fiecho -e "\n=== GitHub workflows related to docs ==="if [ -d".github/workflows" ];then
find .github/workflows -name "*.yml" -o -name "*.yaml"| head -20
fiecho -e "\n=== Repository name from git config ==="
git config --get remote.origin.url ||echo"Not a git repo"

Repository: MetaState-Prototype-Project/prototype

Length of output: 1398

---

🏁 Script executed:

#!/bin/bash# Examine docusaurus.config.ts to see full contextecho"=== Full docusaurus.config.ts (first 50 lines) ==="
head -50 docs/docusaurus.config.ts
echo -e "\n=== Checking for baseUrl and deploying related config ==="
rg -n "baseUrl|organizationName|projectName|url:" docs/docusaurus.config.ts -A 1 -B 1

Repository: MetaState-Prototype-Project/prototype

Length of output: 1993

---

🏁 Script executed:

#!/bin/bash# Look for any GitHub Actions workflows that might handle docs deploymentecho"=== Looking for docs-related workflows ==="
find .github/workflows -type f \( -name "*.yml" -o -name "*.yaml"\)2>/dev/null |whileread file;doecho"File: $file"if grep -q "docs\|docusaurus\|gh-pages""$file";thenecho"--- Content ---"
cat "$file"echo""fidone

Repository: MetaState-Prototype-Project/prototype

Length of output: 1817

---

Update projectName to match the actual repository name.

Line 28 sets projectName to 'metastate', but the repository is prototype. While the GitHub workflow bypasses docusaurus deploy and uses GitHub Pages directly, the docs/README.md instructs users to run GIT_USER=<username> yarn deploy, which relies on these settings. Running the deploy script would attempt to push to the wrong repository. Change projectName to 'prototype'.

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 23 - 28, The projectName value in the
Docusaurus config is incorrect; update the projectName symbol in the
configuration (currently set to 'metastate') to 'prototype' so deploy scripts
that rely on projectName (e.g., the GIT_USER yarn deploy flow referenced in
docs/README.md) will target the correct GitHub repo; leave organizationName
unchanged and run a quick deploy dry-run to confirm settings.

[nsergey82]

would be really nice if we had at least one example of each type somewhere. E.g., I have no idea from the top of my head how a "ledger" meta envelope may look like

[coodos]

@nsergey82 for these examples I imagine the better place would be the ontology viewer and not the docs, as then the docs may start to get more bloated.

[nsergey82]

not any w3ids, just the ename (according to out definitions)?

[nsergey82]

does it actually verify tokens, or merely provide us with material needed for such verification on our side?

[nsergey82]

this is obviously one of the candidates for pagination, but also rate limiting

[coodos]

pagination for this is being added

[coodos]

Description of change

Add docs for ontology and registry

Issue Number

closes#751

Type of change

• Docs (changes to the documentation)

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

Summary by CodeRabbit

Release Notes

• Documentation

  • Added comprehensive documentation for Ontology and Registry services
  • Added Links reference page with production service URLs
  • Enhanced cross-linking across documentation for improved navigation
  • Updated terminology for clarity and consistency

• Site Updates

  • Updated domain to docs.w3ds.metastate.foundation
  • Refreshed branding with W3DS logo
  • Improved navigation structure in footer and menu

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR comprehensively restructures documentation by adding new service pages (Registry, Ontology, Links), adding internal cross-links throughout existing documentation, updating terminology from UUID to W3ID-based references, and refreshing Docusaurus configuration with production URLs and branding changes.

Changes

Cohort / File(s)	Summary
New Infrastructure Documentation docs/docs/Infrastructure/Ontology.md, docs/docs/Infrastructure/Registry.md, docs/docs/W3DS Basics/Links.md	Introduces three new documentation files: Ontology describes JSON Schema registry and W3ID schema identifiers; Registry details service discovery, entropy generation, and key binding certificates; Links provides a reference table of production service URLs.
Cross-linked Infrastructure Pages docs/docs/Infrastructure/eVault.md, docs/docs/Infrastructure/Web3-Adapter.md, docs/docs/Infrastructure/eID-Wallet.md, docs/docs/Infrastructure/eVault-Key-Delegation.md, docs/docs/Getting Started/getting-started.md	Adds internal hyperlinks to related documentation, replaces UUID references with W3ID terminology, updates service descriptions to reference Registry and Ontology pages, and links key concepts (MetaEnvelope, Bearer tokens, key binding certificates).
Cross-linked W3DS Basics & Protocol Pages docs/docs/W3DS Basics/W3ID.md, docs/docs/W3DS Basics/getting-started.md, docs/docs/W3DS Protocol/Authentication.md, docs/docs/W3DS Protocol/Signing.md, docs/docs/W3DS Protocol/Signature-Formats.md, docs/docs/W3DS Protocol/Awareness-Protocol.md	Converts plain references to Markdown links for eVault, Registry, eID Wallet, and Ontology; updates session identifier terminology from UUID to cryptographically secure 128-bit session ID; standardizes namespace generation descriptions.
Cross-linked Post Platform Guide docs/docs/Post Platform Guide/getting-started.md, docs/docs/Post Platform Guide/mapping-rules.md, docs/docs/Post Platform Guide/webhook-controller.md	Adds links to Authentication, Signing, eVault, Registry, Ontology, and Web3 Adapter docs; updates schemaId references from UUID to W3ID format; expands References sections with linked resources.
Docusaurus Configuration & Navigation docs/docusaurus.config.ts, docs/src/pages/index.tsx, README.md	Updates production URL to https://docs.w3ds.metastate.foundation, changes favicon to W3DS logo, updates navbar label from "Tutorial" to "Docs", expands footer links to include W3DS Basics, Infrastructure, and Links; modifies home page redirect to respect baseUrl configuration and updates page metadata.
Category Navigation docs/docs/Getting Started/_category_.json, docs/docs/Post Platform Guide/_category_.json, docs/docs/W3DS Basics/_category_.json, docs/docs/W3DS Protocol/_category_.json	Removes generated-index link metadata from category configuration files while retaining position and label fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related issues

• [question] Registry documentation 🧐 #109: The new Registry.md documentation directly addresses protocol concerns by detailing endpoints (/resolve, /entropy, /.well-known/jwks.json) and cross-linking Registry behavior throughout the documentation.

Possibly related PRs

• docs: add infrastructure, protocol, and getting started docs #721: Overlapping documentation changes in Getting Started, eVault, eID-Wallet, Registry, and related infrastructure docs.
• Fix/dreamsync recommendations #691: Both PRs modify docs/src/pages/index.tsx for redirect logic and metadata updates.
• docs: add docs for key delegation and auth #720: Both PRs modify authentication and eVault-Key-Delegation documentation with cross-references and terminology updates.

Suggested reviewers

• xPathin
• sosweetham
• JulienAuvo

Poem

🐰 Hops through the docs with glee,
Cross-links now guide discovery,
W3IDs dance, no UUIDs here—
The Registry's mirror, crystal clear,
A foundation of knowledge, anchored and neat,
Documentation's heart, now complete! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Docs/ontology and registry' is concise and directly references the main additions (ontology and registry documentation), aligning with the substantial changes across multiple docs.
Description check	✅ Passed	The PR description follows the required template with all key sections: change description, issue number, type of change, and completed checklist items.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/ontology-and-registry

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/docs/Post Platform Guide/getting-started.md (1)

64-85: ⚠️ Potential issue | 🟠 Major

Fix the auth request body to use w3id as the user identifier (and drop the eVault URL).

The example shows w3id as an eVault URL and also includes ename. This conflicts with the signing/verification flow that identifies users by w3id (eName). Use w3id as the identifier and remove the redundant ename. Based on learnings, the correct parameter name is w3id for user identification.

✅ Suggested doc correction

-{- "ename": "@user.w3id",- "session": "abc123...",- "w3id": "https://evault.example.com/users/123",- "signature": "z..."-}+{+ "w3id": "@user.w3id",+ "session": "abc123...",+ "signature": "z..."+}

- const { ename, session, signature } = req.body;+ const { w3id, session, signature } = req.body;
// Verify signature using signature-validator ...
const verificationResult = await verifySignature({
- eName: ename,+ eName: w3id,
signature: signature,
payload: session,
registryBaseUrl: process.env.PUBLIC_REGISTRY_URL,
});
- const user = await this.userService.findUser(ename);+ const user = await this.userService.findUser(w3id);

Also applies to: 76-99

🤖 Fix all issues with AI agents

In `@docs/docs/Post` Platform Guide/mapping-rules.md:
- Line 16: The examples are inconsistent: the top example uses "schemaId":
"global_schema_w3id" while later examples use UUIDs; update the examples that
set "schemaId" (the example occurrences that currently use
"550e8400-e29b-41d4-a716-446655440000") to match the W3ID format used in the
basic structure, or alternatively add a short clarifying sentence after the
basic structure explaining that "schemaId" may be either a W3ID (e.g.,
"global_schema_w3id") or a UUID and show both example variants; locate and edit
the example blocks that define schemaId to ensure consistent formatting or add
the explanatory note.
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 28-29: The anchor link targeting fromGlobal is broken: update the
link target (currently pointing to /docs/Infrastructure/Web3-Adapter#fromGlobal)
by either adding a dedicated heading "fromGlobal" (e.g., create a `###
fromGlobal` section so the anchor exists) in the Web3-Adapter document where the
fromGlobal function is discussed, or change the reference to an existing,
specific section such as `#receiving-data-inbound` where fromGlobal is covered;
ensure the Markdown heading text matches the anchor slug so the link resolves.

🧹 Nitpick comments (2)

docs/docs/W3DS Protocol/Signature-Formats.md (1)

324-324: Consider clarifying "unique identifier" terminology.

The change from "Create a UUID v4 for the namespace identifier" to "Create a unique identifier for the namespace" makes the terminology more generic. While this provides flexibility, it may leave readers uncertain about what format to use.

Consider either:

1. Keeping the UUID v4 specificity if that's the expected format, or
2. Adding a brief note about acceptable formats (e.g., "such as a UUID v4")

📝 Optional clarification

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a unique identifier for the namespace (e.g., UUID v4)

or, if any unique identifier is acceptable:

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a globally unique identifier for the namespace (such as UUID v4 or similar)

Also applies to: 329-329

docs/docs/W3DS Protocol/Authentication.md (1)

91-101: Align the reference snippet with the “session ID” terminology.

The text avoids UUID wording, but the example still uses uuidv4() and session. Consider renaming to sessionId and using a generic cryptographically secure generator (or add a short note that UUIDv4 is an acceptable 128‑bit session ID). This keeps terminology consistent and reduces reader confusion.

💡 Possible doc tweak

- const session = uuidv4();- const offer = `w3ds://auth?redirect=${url}&session=${session}&platform=blabsy`;+ const sessionId = crypto.randomUUID(); // 128-bit session ID+ const offer = `w3ds://auth?redirect=${url}&session=${sessionId}&platform=blabsy`;

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 49-52: The docs configuration's editUrl is pointing to the wrong
repository; update the docs.editUrl string in docusaurus.config.ts to the
correct GitHub repository path for this project (replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.
In `@docs/src/pages/index.tsx`:
- Around line 11-14: Normalize siteConfig.baseUrl to always end with a trailing
slash and avoid history.push on the homepage to prevent back-button loops: in
the useEffect referencing siteConfig.baseUrl and history.push, compute a safe
baseUrl (ensure it defaults to '/' and appends a '/' if missing), only run the
redirect when the current location pathname is the root (so you don't redirect
from nested pages), and use history.replace instead of history.push to perform
the navigation to `${baseUrl}docs/Getting%20Started/getting-started`; update
references to useEffect, siteConfig.baseUrl, and history.replace/history.push
accordingly.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Edit URL points to the wrong repository.
This appears to target a different repo name, which will break “Edit this page” links.

🔧 Proposed fix

- editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',+ editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',

📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	docs: {
	sidebarPath: './sidebars.ts',
	// Please change this to your repo.
	// Remove this to remove the "edit this page" links.
	editUrl:
	'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
	editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',
	},
	docs: {
	sidebarPath: './sidebars.ts',
	editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',
	},

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 49 - 52, The docs configuration's
editUrl is pointing to the wrong repository; update the docs.editUrl string in
docusaurus.config.ts to the correct GitHub repository path for this project
(replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/docusaurus.yml:
- Line 4: The workflow currently triggers on pull_request which allows the
deploy job to run for PRs; modify the deploy job (named "deploy" in the
docusaurus.yml) to skip runs on PR events by adding a job-level condition such
as checking the event name or branch (e.g., add an if condition like
github.event_name != 'pull_request' or require github.ref == 'refs/heads/main'
&& github.event_name == 'push') so deploy only runs on real pushes to the
production branch; apply the same guard to the other affected deploy-related
jobs referenced around the block noted (lines 39-57) to prevent accidental PR
deployments.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 23-28: The projectName value in the Docusaurus config is
incorrect; update the projectName symbol in the configuration (currently set to
'metastate') to 'prototype' so deploy scripts that rely on projectName (e.g.,
the GIT_USER yarn deploy flow referenced in docs/README.md) will target the
correct GitHub repo; leave organizationName unchanged and run a quick deploy
dry-run to confirm settings.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash# Look for Docusaurus deploy / gh-pages usage and repo configurationecho"=== Searching for deploy references ==="
rg -n "docusaurus deploy|gh-pages|npm run deploy|yarn deploy|pnpm deploy" --max-count=20
echo -e "\n=== Checking package.json for deploy scripts ==="if [ -f"package.json" ];then
cat package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" package.json ||echo"No deploy scripts found"fiecho -e "\n=== Checking docs/package.json ==="if [ -f"docs/package.json" ];then
cat docs/package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" docs/package.json ||echo"No deploy scripts found"fiecho -e "\n=== GitHub workflows related to docs ==="if [ -d".github/workflows" ];then
find .github/workflows -name "*.yml" -o -name "*.yaml"| head -20
fiecho -e "\n=== Repository name from git config ==="
git config --get remote.origin.url ||echo"Not a git repo"

Repository: MetaState-Prototype-Project/prototype

Length of output: 1398

---

🏁 Script executed:

#!/bin/bash# Examine docusaurus.config.ts to see full contextecho"=== Full docusaurus.config.ts (first 50 lines) ==="
head -50 docs/docusaurus.config.ts
echo -e "\n=== Checking for baseUrl and deploying related config ==="
rg -n "baseUrl|organizationName|projectName|url:" docs/docusaurus.config.ts -A 1 -B 1

Repository: MetaState-Prototype-Project/prototype

Length of output: 1993

---

🏁 Script executed:

#!/bin/bash# Look for any GitHub Actions workflows that might handle docs deploymentecho"=== Looking for docs-related workflows ==="
find .github/workflows -type f \( -name "*.yml" -o -name "*.yaml"\)2>/dev/null |whileread file;doecho"File: $file"if grep -q "docs\|docusaurus\|gh-pages""$file";thenecho"--- Content ---"
cat "$file"echo""fidone

Repository: MetaState-Prototype-Project/prototype

Length of output: 1817

---

Update projectName to match the actual repository name.

Line 28 sets projectName to 'metastate', but the repository is prototype. While the GitHub workflow bypasses docusaurus deploy and uses GitHub Pages directly, the docs/README.md instructs users to run GIT_USER=<username> yarn deploy, which relies on these settings. Running the deploy script would attempt to push to the wrong repository. Change projectName to 'prototype'.

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 23 - 28, The projectName value in the
Docusaurus config is incorrect; update the projectName symbol in the
configuration (currently set to 'metastate') to 'prototype' so deploy scripts
that rely on projectName (e.g., the GIT_USER yarn deploy flow referenced in
docs/README.md) will target the correct GitHub repo; leave organizationName
unchanged and run a quick deploy dry-run to confirm settings.

[nsergey82]

would be really nice if we had at least one example of each type somewhere. E.g., I have no idea from the top of my head how a "ledger" meta envelope may look like

[coodos]

@nsergey82 for these examples I imagine the better place would be the ontology viewer and not the docs, as then the docs may start to get more bloated.

[nsergey82]

not any w3ids, just the ename (according to out definitions)?

[nsergey82]

does it actually verify tokens, or merely provide us with material needed for such verification on our side?

[nsergey82]

this is obviously one of the candidates for pagination, but also rate limiting

[coodos]

pagination for this is being added

[coodos]

Description of change

Add docs for ontology and registry

Issue Number

closes#751

Type of change

• Docs (changes to the documentation)

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

Summary by CodeRabbit

Release Notes

• Documentation

  • Added comprehensive documentation for Ontology and Registry services
  • Added Links reference page with production service URLs
  • Enhanced cross-linking across documentation for improved navigation
  • Updated terminology for clarity and consistency

• Site Updates

  • Updated domain to docs.w3ds.metastate.foundation
  • Refreshed branding with W3DS logo
  • Improved navigation structure in footer and menu

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR comprehensively restructures documentation by adding new service pages (Registry, Ontology, Links), adding internal cross-links throughout existing documentation, updating terminology from UUID to W3ID-based references, and refreshing Docusaurus configuration with production URLs and branding changes.

Changes

Cohort / File(s)	Summary
New Infrastructure Documentation docs/docs/Infrastructure/Ontology.md, docs/docs/Infrastructure/Registry.md, docs/docs/W3DS Basics/Links.md	Introduces three new documentation files: Ontology describes JSON Schema registry and W3ID schema identifiers; Registry details service discovery, entropy generation, and key binding certificates; Links provides a reference table of production service URLs.
Cross-linked Infrastructure Pages docs/docs/Infrastructure/eVault.md, docs/docs/Infrastructure/Web3-Adapter.md, docs/docs/Infrastructure/eID-Wallet.md, docs/docs/Infrastructure/eVault-Key-Delegation.md, docs/docs/Getting Started/getting-started.md	Adds internal hyperlinks to related documentation, replaces UUID references with W3ID terminology, updates service descriptions to reference Registry and Ontology pages, and links key concepts (MetaEnvelope, Bearer tokens, key binding certificates).
Cross-linked W3DS Basics & Protocol Pages docs/docs/W3DS Basics/W3ID.md, docs/docs/W3DS Basics/getting-started.md, docs/docs/W3DS Protocol/Authentication.md, docs/docs/W3DS Protocol/Signing.md, docs/docs/W3DS Protocol/Signature-Formats.md, docs/docs/W3DS Protocol/Awareness-Protocol.md	Converts plain references to Markdown links for eVault, Registry, eID Wallet, and Ontology; updates session identifier terminology from UUID to cryptographically secure 128-bit session ID; standardizes namespace generation descriptions.
Cross-linked Post Platform Guide docs/docs/Post Platform Guide/getting-started.md, docs/docs/Post Platform Guide/mapping-rules.md, docs/docs/Post Platform Guide/webhook-controller.md	Adds links to Authentication, Signing, eVault, Registry, Ontology, and Web3 Adapter docs; updates schemaId references from UUID to W3ID format; expands References sections with linked resources.
Docusaurus Configuration & Navigation docs/docusaurus.config.ts, docs/src/pages/index.tsx, README.md	Updates production URL to https://docs.w3ds.metastate.foundation, changes favicon to W3DS logo, updates navbar label from "Tutorial" to "Docs", expands footer links to include W3DS Basics, Infrastructure, and Links; modifies home page redirect to respect baseUrl configuration and updates page metadata.
Category Navigation docs/docs/Getting Started/_category_.json, docs/docs/Post Platform Guide/_category_.json, docs/docs/W3DS Basics/_category_.json, docs/docs/W3DS Protocol/_category_.json	Removes generated-index link metadata from category configuration files while retaining position and label fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related issues

• [question] Registry documentation 🧐 #109: The new Registry.md documentation directly addresses protocol concerns by detailing endpoints (/resolve, /entropy, /.well-known/jwks.json) and cross-linking Registry behavior throughout the documentation.

Possibly related PRs

• docs: add infrastructure, protocol, and getting started docs #721: Overlapping documentation changes in Getting Started, eVault, eID-Wallet, Registry, and related infrastructure docs.
• Fix/dreamsync recommendations #691: Both PRs modify docs/src/pages/index.tsx for redirect logic and metadata updates.
• docs: add docs for key delegation and auth #720: Both PRs modify authentication and eVault-Key-Delegation documentation with cross-references and terminology updates.

Suggested reviewers

• xPathin
• sosweetham
• JulienAuvo

Poem

🐰 Hops through the docs with glee,
Cross-links now guide discovery,
W3IDs dance, no UUIDs here—
The Registry's mirror, crystal clear,
A foundation of knowledge, anchored and neat,
Documentation's heart, now complete! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Docs/ontology and registry' is concise and directly references the main additions (ontology and registry documentation), aligning with the substantial changes across multiple docs.
Description check	✅ Passed	The PR description follows the required template with all key sections: change description, issue number, type of change, and completed checklist items.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/ontology-and-registry

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/docs/Post Platform Guide/getting-started.md (1)

64-85: ⚠️ Potential issue | 🟠 Major

Fix the auth request body to use w3id as the user identifier (and drop the eVault URL).

The example shows w3id as an eVault URL and also includes ename. This conflicts with the signing/verification flow that identifies users by w3id (eName). Use w3id as the identifier and remove the redundant ename. Based on learnings, the correct parameter name is w3id for user identification.

✅ Suggested doc correction

-{- "ename": "@user.w3id",- "session": "abc123...",- "w3id": "https://evault.example.com/users/123",- "signature": "z..."-}+{+ "w3id": "@user.w3id",+ "session": "abc123...",+ "signature": "z..."+}

- const { ename, session, signature } = req.body;+ const { w3id, session, signature } = req.body;
// Verify signature using signature-validator ...
const verificationResult = await verifySignature({
- eName: ename,+ eName: w3id,
signature: signature,
payload: session,
registryBaseUrl: process.env.PUBLIC_REGISTRY_URL,
});
- const user = await this.userService.findUser(ename);+ const user = await this.userService.findUser(w3id);

Also applies to: 76-99

🤖 Fix all issues with AI agents

In `@docs/docs/Post` Platform Guide/mapping-rules.md:
- Line 16: The examples are inconsistent: the top example uses "schemaId":
"global_schema_w3id" while later examples use UUIDs; update the examples that
set "schemaId" (the example occurrences that currently use
"550e8400-e29b-41d4-a716-446655440000") to match the W3ID format used in the
basic structure, or alternatively add a short clarifying sentence after the
basic structure explaining that "schemaId" may be either a W3ID (e.g.,
"global_schema_w3id") or a UUID and show both example variants; locate and edit
the example blocks that define schemaId to ensure consistent formatting or add
the explanatory note.
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 28-29: The anchor link targeting fromGlobal is broken: update the
link target (currently pointing to /docs/Infrastructure/Web3-Adapter#fromGlobal)
by either adding a dedicated heading "fromGlobal" (e.g., create a `###
fromGlobal` section so the anchor exists) in the Web3-Adapter document where the
fromGlobal function is discussed, or change the reference to an existing,
specific section such as `#receiving-data-inbound` where fromGlobal is covered;
ensure the Markdown heading text matches the anchor slug so the link resolves.

🧹 Nitpick comments (2)

docs/docs/W3DS Protocol/Signature-Formats.md (1)

324-324: Consider clarifying "unique identifier" terminology.

The change from "Create a UUID v4 for the namespace identifier" to "Create a unique identifier for the namespace" makes the terminology more generic. While this provides flexibility, it may leave readers uncertain about what format to use.

Consider either:

1. Keeping the UUID v4 specificity if that's the expected format, or
2. Adding a brief note about acceptable formats (e.g., "such as a UUID v4")

📝 Optional clarification

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a unique identifier for the namespace (e.g., UUID v4)

or, if any unique identifier is acceptable:

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a globally unique identifier for the namespace (such as UUID v4 or similar)

Also applies to: 329-329

docs/docs/W3DS Protocol/Authentication.md (1)

91-101: Align the reference snippet with the “session ID” terminology.

The text avoids UUID wording, but the example still uses uuidv4() and session. Consider renaming to sessionId and using a generic cryptographically secure generator (or add a short note that UUIDv4 is an acceptable 128‑bit session ID). This keeps terminology consistent and reduces reader confusion.

💡 Possible doc tweak

- const session = uuidv4();- const offer = `w3ds://auth?redirect=${url}&session=${session}&platform=blabsy`;+ const sessionId = crypto.randomUUID(); // 128-bit session ID+ const offer = `w3ds://auth?redirect=${url}&session=${sessionId}&platform=blabsy`;

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 49-52: The docs configuration's editUrl is pointing to the wrong
repository; update the docs.editUrl string in docusaurus.config.ts to the
correct GitHub repository path for this project (replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.
In `@docs/src/pages/index.tsx`:
- Around line 11-14: Normalize siteConfig.baseUrl to always end with a trailing
slash and avoid history.push on the homepage to prevent back-button loops: in
the useEffect referencing siteConfig.baseUrl and history.push, compute a safe
baseUrl (ensure it defaults to '/' and appends a '/' if missing), only run the
redirect when the current location pathname is the root (so you don't redirect
from nested pages), and use history.replace instead of history.push to perform
the navigation to `${baseUrl}docs/Getting%20Started/getting-started`; update
references to useEffect, siteConfig.baseUrl, and history.replace/history.push
accordingly.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Edit URL points to the wrong repository.
This appears to target a different repo name, which will break “Edit this page” links.

🔧 Proposed fix

- editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',+ editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',

📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	docs: {
	sidebarPath: './sidebars.ts',
	// Please change this to your repo.
	// Remove this to remove the "edit this page" links.
	editUrl:
	'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
	editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',
	},
	docs: {
	sidebarPath: './sidebars.ts',
	editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',
	},

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 49 - 52, The docs configuration's
editUrl is pointing to the wrong repository; update the docs.editUrl string in
docusaurus.config.ts to the correct GitHub repository path for this project
(replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/docusaurus.yml:
- Line 4: The workflow currently triggers on pull_request which allows the
deploy job to run for PRs; modify the deploy job (named "deploy" in the
docusaurus.yml) to skip runs on PR events by adding a job-level condition such
as checking the event name or branch (e.g., add an if condition like
github.event_name != 'pull_request' or require github.ref == 'refs/heads/main'
&& github.event_name == 'push') so deploy only runs on real pushes to the
production branch; apply the same guard to the other affected deploy-related
jobs referenced around the block noted (lines 39-57) to prevent accidental PR
deployments.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 23-28: The projectName value in the Docusaurus config is
incorrect; update the projectName symbol in the configuration (currently set to
'metastate') to 'prototype' so deploy scripts that rely on projectName (e.g.,
the GIT_USER yarn deploy flow referenced in docs/README.md) will target the
correct GitHub repo; leave organizationName unchanged and run a quick deploy
dry-run to confirm settings.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash# Look for Docusaurus deploy / gh-pages usage and repo configurationecho"=== Searching for deploy references ==="
rg -n "docusaurus deploy|gh-pages|npm run deploy|yarn deploy|pnpm deploy" --max-count=20
echo -e "\n=== Checking package.json for deploy scripts ==="if [ -f"package.json" ];then
cat package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" package.json ||echo"No deploy scripts found"fiecho -e "\n=== Checking docs/package.json ==="if [ -f"docs/package.json" ];then
cat docs/package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" docs/package.json ||echo"No deploy scripts found"fiecho -e "\n=== GitHub workflows related to docs ==="if [ -d".github/workflows" ];then
find .github/workflows -name "*.yml" -o -name "*.yaml"| head -20
fiecho -e "\n=== Repository name from git config ==="
git config --get remote.origin.url ||echo"Not a git repo"

Repository: MetaState-Prototype-Project/prototype

Length of output: 1398

---

🏁 Script executed:

#!/bin/bash# Examine docusaurus.config.ts to see full contextecho"=== Full docusaurus.config.ts (first 50 lines) ==="
head -50 docs/docusaurus.config.ts
echo -e "\n=== Checking for baseUrl and deploying related config ==="
rg -n "baseUrl|organizationName|projectName|url:" docs/docusaurus.config.ts -A 1 -B 1

Repository: MetaState-Prototype-Project/prototype

Length of output: 1993

---

🏁 Script executed:

#!/bin/bash# Look for any GitHub Actions workflows that might handle docs deploymentecho"=== Looking for docs-related workflows ==="
find .github/workflows -type f \( -name "*.yml" -o -name "*.yaml"\)2>/dev/null |whileread file;doecho"File: $file"if grep -q "docs\|docusaurus\|gh-pages""$file";thenecho"--- Content ---"
cat "$file"echo""fidone

Repository: MetaState-Prototype-Project/prototype

Length of output: 1817

---

Update projectName to match the actual repository name.

Line 28 sets projectName to 'metastate', but the repository is prototype. While the GitHub workflow bypasses docusaurus deploy and uses GitHub Pages directly, the docs/README.md instructs users to run GIT_USER=<username> yarn deploy, which relies on these settings. Running the deploy script would attempt to push to the wrong repository. Change projectName to 'prototype'.

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 23 - 28, The projectName value in the
Docusaurus config is incorrect; update the projectName symbol in the
configuration (currently set to 'metastate') to 'prototype' so deploy scripts
that rely on projectName (e.g., the GIT_USER yarn deploy flow referenced in
docs/README.md) will target the correct GitHub repo; leave organizationName
unchanged and run a quick deploy dry-run to confirm settings.

[nsergey82]

would be really nice if we had at least one example of each type somewhere. E.g., I have no idea from the top of my head how a "ledger" meta envelope may look like

[coodos]

@nsergey82 for these examples I imagine the better place would be the ontology viewer and not the docs, as then the docs may start to get more bloated.

[nsergey82]

not any w3ids, just the ename (according to out definitions)?

[nsergey82]

does it actually verify tokens, or merely provide us with material needed for such verification on our side?

[nsergey82]

this is obviously one of the candidates for pagination, but also rate limiting

[coodos]

pagination for this is being added

[coodos]

Description of change

Add docs for ontology and registry

Issue Number

closes#751

Type of change

• Docs (changes to the documentation)

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

Summary by CodeRabbit

Release Notes

• Documentation

  • Added comprehensive documentation for Ontology and Registry services
  • Added Links reference page with production service URLs
  • Enhanced cross-linking across documentation for improved navigation
  • Updated terminology for clarity and consistency

• Site Updates

  • Updated domain to docs.w3ds.metastate.foundation
  • Refreshed branding with W3DS logo
  • Improved navigation structure in footer and menu

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR comprehensively restructures documentation by adding new service pages (Registry, Ontology, Links), adding internal cross-links throughout existing documentation, updating terminology from UUID to W3ID-based references, and refreshing Docusaurus configuration with production URLs and branding changes.

Changes

Cohort / File(s)	Summary
New Infrastructure Documentation docs/docs/Infrastructure/Ontology.md, docs/docs/Infrastructure/Registry.md, docs/docs/W3DS Basics/Links.md	Introduces three new documentation files: Ontology describes JSON Schema registry and W3ID schema identifiers; Registry details service discovery, entropy generation, and key binding certificates; Links provides a reference table of production service URLs.
Cross-linked Infrastructure Pages docs/docs/Infrastructure/eVault.md, docs/docs/Infrastructure/Web3-Adapter.md, docs/docs/Infrastructure/eID-Wallet.md, docs/docs/Infrastructure/eVault-Key-Delegation.md, docs/docs/Getting Started/getting-started.md	Adds internal hyperlinks to related documentation, replaces UUID references with W3ID terminology, updates service descriptions to reference Registry and Ontology pages, and links key concepts (MetaEnvelope, Bearer tokens, key binding certificates).
Cross-linked W3DS Basics & Protocol Pages docs/docs/W3DS Basics/W3ID.md, docs/docs/W3DS Basics/getting-started.md, docs/docs/W3DS Protocol/Authentication.md, docs/docs/W3DS Protocol/Signing.md, docs/docs/W3DS Protocol/Signature-Formats.md, docs/docs/W3DS Protocol/Awareness-Protocol.md	Converts plain references to Markdown links for eVault, Registry, eID Wallet, and Ontology; updates session identifier terminology from UUID to cryptographically secure 128-bit session ID; standardizes namespace generation descriptions.
Cross-linked Post Platform Guide docs/docs/Post Platform Guide/getting-started.md, docs/docs/Post Platform Guide/mapping-rules.md, docs/docs/Post Platform Guide/webhook-controller.md	Adds links to Authentication, Signing, eVault, Registry, Ontology, and Web3 Adapter docs; updates schemaId references from UUID to W3ID format; expands References sections with linked resources.
Docusaurus Configuration & Navigation docs/docusaurus.config.ts, docs/src/pages/index.tsx, README.md	Updates production URL to https://docs.w3ds.metastate.foundation, changes favicon to W3DS logo, updates navbar label from "Tutorial" to "Docs", expands footer links to include W3DS Basics, Infrastructure, and Links; modifies home page redirect to respect baseUrl configuration and updates page metadata.
Category Navigation docs/docs/Getting Started/_category_.json, docs/docs/Post Platform Guide/_category_.json, docs/docs/W3DS Basics/_category_.json, docs/docs/W3DS Protocol/_category_.json	Removes generated-index link metadata from category configuration files while retaining position and label fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related issues

• [question] Registry documentation 🧐 #109: The new Registry.md documentation directly addresses protocol concerns by detailing endpoints (/resolve, /entropy, /.well-known/jwks.json) and cross-linking Registry behavior throughout the documentation.

Possibly related PRs

• docs: add infrastructure, protocol, and getting started docs #721: Overlapping documentation changes in Getting Started, eVault, eID-Wallet, Registry, and related infrastructure docs.
• Fix/dreamsync recommendations #691: Both PRs modify docs/src/pages/index.tsx for redirect logic and metadata updates.
• docs: add docs for key delegation and auth #720: Both PRs modify authentication and eVault-Key-Delegation documentation with cross-references and terminology updates.

Suggested reviewers

• xPathin
• sosweetham
• JulienAuvo

Poem

🐰 Hops through the docs with glee,
Cross-links now guide discovery,
W3IDs dance, no UUIDs here—
The Registry's mirror, crystal clear,
A foundation of knowledge, anchored and neat,
Documentation's heart, now complete! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Docs/ontology and registry' is concise and directly references the main additions (ontology and registry documentation), aligning with the substantial changes across multiple docs.
Description check	✅ Passed	The PR description follows the required template with all key sections: change description, issue number, type of change, and completed checklist items.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/ontology-and-registry

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/docs/Post Platform Guide/getting-started.md (1)

64-85: ⚠️ Potential issue | 🟠 Major

Fix the auth request body to use w3id as the user identifier (and drop the eVault URL).

The example shows w3id as an eVault URL and also includes ename. This conflicts with the signing/verification flow that identifies users by w3id (eName). Use w3id as the identifier and remove the redundant ename. Based on learnings, the correct parameter name is w3id for user identification.

✅ Suggested doc correction

-{- "ename": "@user.w3id",- "session": "abc123...",- "w3id": "https://evault.example.com/users/123",- "signature": "z..."-}+{+ "w3id": "@user.w3id",+ "session": "abc123...",+ "signature": "z..."+}

- const { ename, session, signature } = req.body;+ const { w3id, session, signature } = req.body;
// Verify signature using signature-validator ...
const verificationResult = await verifySignature({
- eName: ename,+ eName: w3id,
signature: signature,
payload: session,
registryBaseUrl: process.env.PUBLIC_REGISTRY_URL,
});
- const user = await this.userService.findUser(ename);+ const user = await this.userService.findUser(w3id);

Also applies to: 76-99

🤖 Fix all issues with AI agents

In `@docs/docs/Post` Platform Guide/mapping-rules.md:
- Line 16: The examples are inconsistent: the top example uses "schemaId":
"global_schema_w3id" while later examples use UUIDs; update the examples that
set "schemaId" (the example occurrences that currently use
"550e8400-e29b-41d4-a716-446655440000") to match the W3ID format used in the
basic structure, or alternatively add a short clarifying sentence after the
basic structure explaining that "schemaId" may be either a W3ID (e.g.,
"global_schema_w3id") or a UUID and show both example variants; locate and edit
the example blocks that define schemaId to ensure consistent formatting or add
the explanatory note.
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 28-29: The anchor link targeting fromGlobal is broken: update the
link target (currently pointing to /docs/Infrastructure/Web3-Adapter#fromGlobal)
by either adding a dedicated heading "fromGlobal" (e.g., create a `###
fromGlobal` section so the anchor exists) in the Web3-Adapter document where the
fromGlobal function is discussed, or change the reference to an existing,
specific section such as `#receiving-data-inbound` where fromGlobal is covered;
ensure the Markdown heading text matches the anchor slug so the link resolves.

🧹 Nitpick comments (2)

docs/docs/W3DS Protocol/Signature-Formats.md (1)

324-324: Consider clarifying "unique identifier" terminology.

The change from "Create a UUID v4 for the namespace identifier" to "Create a unique identifier for the namespace" makes the terminology more generic. While this provides flexibility, it may leave readers uncertain about what format to use.

Consider either:

1. Keeping the UUID v4 specificity if that's the expected format, or
2. Adding a brief note about acceptable formats (e.g., "such as a UUID v4")

📝 Optional clarification

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a unique identifier for the namespace (e.g., UUID v4)

or, if any unique identifier is acceptable:

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a globally unique identifier for the namespace (such as UUID v4 or similar)

Also applies to: 329-329

docs/docs/W3DS Protocol/Authentication.md (1)

91-101: Align the reference snippet with the “session ID” terminology.

The text avoids UUID wording, but the example still uses uuidv4() and session. Consider renaming to sessionId and using a generic cryptographically secure generator (or add a short note that UUIDv4 is an acceptable 128‑bit session ID). This keeps terminology consistent and reduces reader confusion.

💡 Possible doc tweak

- const session = uuidv4();- const offer = `w3ds://auth?redirect=${url}&session=${session}&platform=blabsy`;+ const sessionId = crypto.randomUUID(); // 128-bit session ID+ const offer = `w3ds://auth?redirect=${url}&session=${sessionId}&platform=blabsy`;

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 49-52: The docs configuration's editUrl is pointing to the wrong
repository; update the docs.editUrl string in docusaurus.config.ts to the
correct GitHub repository path for this project (replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.
In `@docs/src/pages/index.tsx`:
- Around line 11-14: Normalize siteConfig.baseUrl to always end with a trailing
slash and avoid history.push on the homepage to prevent back-button loops: in
the useEffect referencing siteConfig.baseUrl and history.push, compute a safe
baseUrl (ensure it defaults to '/' and appends a '/' if missing), only run the
redirect when the current location pathname is the root (so you don't redirect
from nested pages), and use history.replace instead of history.push to perform
the navigation to `${baseUrl}docs/Getting%20Started/getting-started`; update
references to useEffect, siteConfig.baseUrl, and history.replace/history.push
accordingly.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Edit URL points to the wrong repository.
This appears to target a different repo name, which will break “Edit this page” links.

🔧 Proposed fix

- editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',+ editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',

📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	docs: {
	sidebarPath: './sidebars.ts',
	// Please change this to your repo.
	// Remove this to remove the "edit this page" links.
	editUrl:
	'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
	editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',
	},
	docs: {
	sidebarPath: './sidebars.ts',
	editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',
	},

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 49 - 52, The docs configuration's
editUrl is pointing to the wrong repository; update the docs.editUrl string in
docusaurus.config.ts to the correct GitHub repository path for this project
(replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/docusaurus.yml:
- Line 4: The workflow currently triggers on pull_request which allows the
deploy job to run for PRs; modify the deploy job (named "deploy" in the
docusaurus.yml) to skip runs on PR events by adding a job-level condition such
as checking the event name or branch (e.g., add an if condition like
github.event_name != 'pull_request' or require github.ref == 'refs/heads/main'
&& github.event_name == 'push') so deploy only runs on real pushes to the
production branch; apply the same guard to the other affected deploy-related
jobs referenced around the block noted (lines 39-57) to prevent accidental PR
deployments.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 23-28: The projectName value in the Docusaurus config is
incorrect; update the projectName symbol in the configuration (currently set to
'metastate') to 'prototype' so deploy scripts that rely on projectName (e.g.,
the GIT_USER yarn deploy flow referenced in docs/README.md) will target the
correct GitHub repo; leave organizationName unchanged and run a quick deploy
dry-run to confirm settings.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash# Look for Docusaurus deploy / gh-pages usage and repo configurationecho"=== Searching for deploy references ==="
rg -n "docusaurus deploy|gh-pages|npm run deploy|yarn deploy|pnpm deploy" --max-count=20
echo -e "\n=== Checking package.json for deploy scripts ==="if [ -f"package.json" ];then
cat package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" package.json ||echo"No deploy scripts found"fiecho -e "\n=== Checking docs/package.json ==="if [ -f"docs/package.json" ];then
cat docs/package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" docs/package.json ||echo"No deploy scripts found"fiecho -e "\n=== GitHub workflows related to docs ==="if [ -d".github/workflows" ];then
find .github/workflows -name "*.yml" -o -name "*.yaml"| head -20
fiecho -e "\n=== Repository name from git config ==="
git config --get remote.origin.url ||echo"Not a git repo"

Repository: MetaState-Prototype-Project/prototype

Length of output: 1398

---

🏁 Script executed:

#!/bin/bash# Examine docusaurus.config.ts to see full contextecho"=== Full docusaurus.config.ts (first 50 lines) ==="
head -50 docs/docusaurus.config.ts
echo -e "\n=== Checking for baseUrl and deploying related config ==="
rg -n "baseUrl|organizationName|projectName|url:" docs/docusaurus.config.ts -A 1 -B 1

Repository: MetaState-Prototype-Project/prototype

Length of output: 1993

---

🏁 Script executed:

#!/bin/bash# Look for any GitHub Actions workflows that might handle docs deploymentecho"=== Looking for docs-related workflows ==="
find .github/workflows -type f \( -name "*.yml" -o -name "*.yaml"\)2>/dev/null |whileread file;doecho"File: $file"if grep -q "docs\|docusaurus\|gh-pages""$file";thenecho"--- Content ---"
cat "$file"echo""fidone

Repository: MetaState-Prototype-Project/prototype

Length of output: 1817

---

Update projectName to match the actual repository name.

Line 28 sets projectName to 'metastate', but the repository is prototype. While the GitHub workflow bypasses docusaurus deploy and uses GitHub Pages directly, the docs/README.md instructs users to run GIT_USER=<username> yarn deploy, which relies on these settings. Running the deploy script would attempt to push to the wrong repository. Change projectName to 'prototype'.

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 23 - 28, The projectName value in the
Docusaurus config is incorrect; update the projectName symbol in the
configuration (currently set to 'metastate') to 'prototype' so deploy scripts
that rely on projectName (e.g., the GIT_USER yarn deploy flow referenced in
docs/README.md) will target the correct GitHub repo; leave organizationName
unchanged and run a quick deploy dry-run to confirm settings.

[nsergey82]

would be really nice if we had at least one example of each type somewhere. E.g., I have no idea from the top of my head how a "ledger" meta envelope may look like

[coodos]

@nsergey82 for these examples I imagine the better place would be the ontology viewer and not the docs, as then the docs may start to get more bloated.

[nsergey82]

not any w3ids, just the ename (according to out definitions)?

[nsergey82]

does it actually verify tokens, or merely provide us with material needed for such verification on our side?

[nsergey82]

this is obviously one of the candidates for pagination, but also rate limiting

[coodos]

pagination for this is being added

[coodos]

Description of change

Add docs for ontology and registry

Issue Number

closes#751

Type of change

• Docs (changes to the documentation)

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

Summary by CodeRabbit

Release Notes

• Documentation

  • Added comprehensive documentation for Ontology and Registry services
  • Added Links reference page with production service URLs
  • Enhanced cross-linking across documentation for improved navigation
  • Updated terminology for clarity and consistency

• Site Updates

  • Updated domain to docs.w3ds.metastate.foundation
  • Refreshed branding with W3DS logo
  • Improved navigation structure in footer and menu

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR comprehensively restructures documentation by adding new service pages (Registry, Ontology, Links), adding internal cross-links throughout existing documentation, updating terminology from UUID to W3ID-based references, and refreshing Docusaurus configuration with production URLs and branding changes.

Changes

Cohort / File(s)	Summary
New Infrastructure Documentation docs/docs/Infrastructure/Ontology.md, docs/docs/Infrastructure/Registry.md, docs/docs/W3DS Basics/Links.md	Introduces three new documentation files: Ontology describes JSON Schema registry and W3ID schema identifiers; Registry details service discovery, entropy generation, and key binding certificates; Links provides a reference table of production service URLs.
Cross-linked Infrastructure Pages docs/docs/Infrastructure/eVault.md, docs/docs/Infrastructure/Web3-Adapter.md, docs/docs/Infrastructure/eID-Wallet.md, docs/docs/Infrastructure/eVault-Key-Delegation.md, docs/docs/Getting Started/getting-started.md	Adds internal hyperlinks to related documentation, replaces UUID references with W3ID terminology, updates service descriptions to reference Registry and Ontology pages, and links key concepts (MetaEnvelope, Bearer tokens, key binding certificates).
Cross-linked W3DS Basics & Protocol Pages docs/docs/W3DS Basics/W3ID.md, docs/docs/W3DS Basics/getting-started.md, docs/docs/W3DS Protocol/Authentication.md, docs/docs/W3DS Protocol/Signing.md, docs/docs/W3DS Protocol/Signature-Formats.md, docs/docs/W3DS Protocol/Awareness-Protocol.md	Converts plain references to Markdown links for eVault, Registry, eID Wallet, and Ontology; updates session identifier terminology from UUID to cryptographically secure 128-bit session ID; standardizes namespace generation descriptions.
Cross-linked Post Platform Guide docs/docs/Post Platform Guide/getting-started.md, docs/docs/Post Platform Guide/mapping-rules.md, docs/docs/Post Platform Guide/webhook-controller.md	Adds links to Authentication, Signing, eVault, Registry, Ontology, and Web3 Adapter docs; updates schemaId references from UUID to W3ID format; expands References sections with linked resources.
Docusaurus Configuration & Navigation docs/docusaurus.config.ts, docs/src/pages/index.tsx, README.md	Updates production URL to https://docs.w3ds.metastate.foundation, changes favicon to W3DS logo, updates navbar label from "Tutorial" to "Docs", expands footer links to include W3DS Basics, Infrastructure, and Links; modifies home page redirect to respect baseUrl configuration and updates page metadata.
Category Navigation docs/docs/Getting Started/_category_.json, docs/docs/Post Platform Guide/_category_.json, docs/docs/W3DS Basics/_category_.json, docs/docs/W3DS Protocol/_category_.json	Removes generated-index link metadata from category configuration files while retaining position and label fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related issues

• [question] Registry documentation 🧐 #109: The new Registry.md documentation directly addresses protocol concerns by detailing endpoints (/resolve, /entropy, /.well-known/jwks.json) and cross-linking Registry behavior throughout the documentation.

Possibly related PRs

• docs: add infrastructure, protocol, and getting started docs #721: Overlapping documentation changes in Getting Started, eVault, eID-Wallet, Registry, and related infrastructure docs.
• Fix/dreamsync recommendations #691: Both PRs modify docs/src/pages/index.tsx for redirect logic and metadata updates.
• docs: add docs for key delegation and auth #720: Both PRs modify authentication and eVault-Key-Delegation documentation with cross-references and terminology updates.

Suggested reviewers

• xPathin
• sosweetham
• JulienAuvo

Poem

🐰 Hops through the docs with glee,
Cross-links now guide discovery,
W3IDs dance, no UUIDs here—
The Registry's mirror, crystal clear,
A foundation of knowledge, anchored and neat,
Documentation's heart, now complete! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Docs/ontology and registry' is concise and directly references the main additions (ontology and registry documentation), aligning with the substantial changes across multiple docs.
Description check	✅ Passed	The PR description follows the required template with all key sections: change description, issue number, type of change, and completed checklist items.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/ontology-and-registry

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/docs/Post Platform Guide/getting-started.md (1)

64-85: ⚠️ Potential issue | 🟠 Major

Fix the auth request body to use w3id as the user identifier (and drop the eVault URL).

The example shows w3id as an eVault URL and also includes ename. This conflicts with the signing/verification flow that identifies users by w3id (eName). Use w3id as the identifier and remove the redundant ename. Based on learnings, the correct parameter name is w3id for user identification.

✅ Suggested doc correction

-{- "ename": "@user.w3id",- "session": "abc123...",- "w3id": "https://evault.example.com/users/123",- "signature": "z..."-}+{+ "w3id": "@user.w3id",+ "session": "abc123...",+ "signature": "z..."+}

- const { ename, session, signature } = req.body;+ const { w3id, session, signature } = req.body;
// Verify signature using signature-validator ...
const verificationResult = await verifySignature({
- eName: ename,+ eName: w3id,
signature: signature,
payload: session,
registryBaseUrl: process.env.PUBLIC_REGISTRY_URL,
});
- const user = await this.userService.findUser(ename);+ const user = await this.userService.findUser(w3id);

Also applies to: 76-99

🤖 Fix all issues with AI agents

In `@docs/docs/Post` Platform Guide/mapping-rules.md:
- Line 16: The examples are inconsistent: the top example uses "schemaId":
"global_schema_w3id" while later examples use UUIDs; update the examples that
set "schemaId" (the example occurrences that currently use
"550e8400-e29b-41d4-a716-446655440000") to match the W3ID format used in the
basic structure, or alternatively add a short clarifying sentence after the
basic structure explaining that "schemaId" may be either a W3ID (e.g.,
"global_schema_w3id") or a UUID and show both example variants; locate and edit
the example blocks that define schemaId to ensure consistent formatting or add
the explanatory note.
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 28-29: The anchor link targeting fromGlobal is broken: update the
link target (currently pointing to /docs/Infrastructure/Web3-Adapter#fromGlobal)
by either adding a dedicated heading "fromGlobal" (e.g., create a `###
fromGlobal` section so the anchor exists) in the Web3-Adapter document where the
fromGlobal function is discussed, or change the reference to an existing,
specific section such as `#receiving-data-inbound` where fromGlobal is covered;
ensure the Markdown heading text matches the anchor slug so the link resolves.

🧹 Nitpick comments (2)

docs/docs/W3DS Protocol/Signature-Formats.md (1)

324-324: Consider clarifying "unique identifier" terminology.

The change from "Create a UUID v4 for the namespace identifier" to "Create a unique identifier for the namespace" makes the terminology more generic. While this provides flexibility, it may leave readers uncertain about what format to use.

Consider either:

1. Keeping the UUID v4 specificity if that's the expected format, or
2. Adding a brief note about acceptable formats (e.g., "such as a UUID v4")

📝 Optional clarification

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a unique identifier for the namespace (e.g., UUID v4)

or, if any unique identifier is acceptable:

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a globally unique identifier for the namespace (such as UUID v4 or similar)

Also applies to: 329-329

docs/docs/W3DS Protocol/Authentication.md (1)

91-101: Align the reference snippet with the “session ID” terminology.

The text avoids UUID wording, but the example still uses uuidv4() and session. Consider renaming to sessionId and using a generic cryptographically secure generator (or add a short note that UUIDv4 is an acceptable 128‑bit session ID). This keeps terminology consistent and reduces reader confusion.

💡 Possible doc tweak

- const session = uuidv4();- const offer = `w3ds://auth?redirect=${url}&session=${session}&platform=blabsy`;+ const sessionId = crypto.randomUUID(); // 128-bit session ID+ const offer = `w3ds://auth?redirect=${url}&session=${sessionId}&platform=blabsy`;

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 49-52: The docs configuration's editUrl is pointing to the wrong
repository; update the docs.editUrl string in docusaurus.config.ts to the
correct GitHub repository path for this project (replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.
In `@docs/src/pages/index.tsx`:
- Around line 11-14: Normalize siteConfig.baseUrl to always end with a trailing
slash and avoid history.push on the homepage to prevent back-button loops: in
the useEffect referencing siteConfig.baseUrl and history.push, compute a safe
baseUrl (ensure it defaults to '/' and appends a '/' if missing), only run the
redirect when the current location pathname is the root (so you don't redirect
from nested pages), and use history.replace instead of history.push to perform
the navigation to `${baseUrl}docs/Getting%20Started/getting-started`; update
references to useEffect, siteConfig.baseUrl, and history.replace/history.push
accordingly.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Edit URL points to the wrong repository.
This appears to target a different repo name, which will break “Edit this page” links.

🔧 Proposed fix

- editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',+ editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',

📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	docs: {
	sidebarPath: './sidebars.ts',
	// Please change this to your repo.
	// Remove this to remove the "edit this page" links.
	editUrl:
	'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
	editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',
	},
	docs: {
	sidebarPath: './sidebars.ts',
	editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',
	},

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 49 - 52, The docs configuration's
editUrl is pointing to the wrong repository; update the docs.editUrl string in
docusaurus.config.ts to the correct GitHub repository path for this project
(replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/docusaurus.yml:
- Line 4: The workflow currently triggers on pull_request which allows the
deploy job to run for PRs; modify the deploy job (named "deploy" in the
docusaurus.yml) to skip runs on PR events by adding a job-level condition such
as checking the event name or branch (e.g., add an if condition like
github.event_name != 'pull_request' or require github.ref == 'refs/heads/main'
&& github.event_name == 'push') so deploy only runs on real pushes to the
production branch; apply the same guard to the other affected deploy-related
jobs referenced around the block noted (lines 39-57) to prevent accidental PR
deployments.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 23-28: The projectName value in the Docusaurus config is
incorrect; update the projectName symbol in the configuration (currently set to
'metastate') to 'prototype' so deploy scripts that rely on projectName (e.g.,
the GIT_USER yarn deploy flow referenced in docs/README.md) will target the
correct GitHub repo; leave organizationName unchanged and run a quick deploy
dry-run to confirm settings.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash# Look for Docusaurus deploy / gh-pages usage and repo configurationecho"=== Searching for deploy references ==="
rg -n "docusaurus deploy|gh-pages|npm run deploy|yarn deploy|pnpm deploy" --max-count=20
echo -e "\n=== Checking package.json for deploy scripts ==="if [ -f"package.json" ];then
cat package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" package.json ||echo"No deploy scripts found"fiecho -e "\n=== Checking docs/package.json ==="if [ -f"docs/package.json" ];then
cat docs/package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" docs/package.json ||echo"No deploy scripts found"fiecho -e "\n=== GitHub workflows related to docs ==="if [ -d".github/workflows" ];then
find .github/workflows -name "*.yml" -o -name "*.yaml"| head -20
fiecho -e "\n=== Repository name from git config ==="
git config --get remote.origin.url ||echo"Not a git repo"

Repository: MetaState-Prototype-Project/prototype

Length of output: 1398

---

🏁 Script executed:

#!/bin/bash# Examine docusaurus.config.ts to see full contextecho"=== Full docusaurus.config.ts (first 50 lines) ==="
head -50 docs/docusaurus.config.ts
echo -e "\n=== Checking for baseUrl and deploying related config ==="
rg -n "baseUrl|organizationName|projectName|url:" docs/docusaurus.config.ts -A 1 -B 1

Repository: MetaState-Prototype-Project/prototype

Length of output: 1993

---

🏁 Script executed:

#!/bin/bash# Look for any GitHub Actions workflows that might handle docs deploymentecho"=== Looking for docs-related workflows ==="
find .github/workflows -type f \( -name "*.yml" -o -name "*.yaml"\)2>/dev/null |whileread file;doecho"File: $file"if grep -q "docs\|docusaurus\|gh-pages""$file";thenecho"--- Content ---"
cat "$file"echo""fidone

Repository: MetaState-Prototype-Project/prototype

Length of output: 1817

---

Update projectName to match the actual repository name.

Line 28 sets projectName to 'metastate', but the repository is prototype. While the GitHub workflow bypasses docusaurus deploy and uses GitHub Pages directly, the docs/README.md instructs users to run GIT_USER=<username> yarn deploy, which relies on these settings. Running the deploy script would attempt to push to the wrong repository. Change projectName to 'prototype'.

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 23 - 28, The projectName value in the
Docusaurus config is incorrect; update the projectName symbol in the
configuration (currently set to 'metastate') to 'prototype' so deploy scripts
that rely on projectName (e.g., the GIT_USER yarn deploy flow referenced in
docs/README.md) will target the correct GitHub repo; leave organizationName
unchanged and run a quick deploy dry-run to confirm settings.

[nsergey82]

would be really nice if we had at least one example of each type somewhere. E.g., I have no idea from the top of my head how a "ledger" meta envelope may look like

[coodos]

@nsergey82 for these examples I imagine the better place would be the ontology viewer and not the docs, as then the docs may start to get more bloated.

[nsergey82]

not any w3ids, just the ename (according to out definitions)?

[nsergey82]

does it actually verify tokens, or merely provide us with material needed for such verification on our side?

[nsergey82]

this is obviously one of the candidates for pagination, but also rate limiting

[coodos]

pagination for this is being added

[coodos]

Description of change

Add docs for ontology and registry

Issue Number

closes#751

Type of change

• Docs (changes to the documentation)

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

Summary by CodeRabbit

Release Notes

• Documentation

  • Added comprehensive documentation for Ontology and Registry services
  • Added Links reference page with production service URLs
  • Enhanced cross-linking across documentation for improved navigation
  • Updated terminology for clarity and consistency

• Site Updates

  • Updated domain to docs.w3ds.metastate.foundation
  • Refreshed branding with W3DS logo
  • Improved navigation structure in footer and menu

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR comprehensively restructures documentation by adding new service pages (Registry, Ontology, Links), adding internal cross-links throughout existing documentation, updating terminology from UUID to W3ID-based references, and refreshing Docusaurus configuration with production URLs and branding changes.

Changes

Cohort / File(s)	Summary
New Infrastructure Documentation docs/docs/Infrastructure/Ontology.md, docs/docs/Infrastructure/Registry.md, docs/docs/W3DS Basics/Links.md	Introduces three new documentation files: Ontology describes JSON Schema registry and W3ID schema identifiers; Registry details service discovery, entropy generation, and key binding certificates; Links provides a reference table of production service URLs.
Cross-linked Infrastructure Pages docs/docs/Infrastructure/eVault.md, docs/docs/Infrastructure/Web3-Adapter.md, docs/docs/Infrastructure/eID-Wallet.md, docs/docs/Infrastructure/eVault-Key-Delegation.md, docs/docs/Getting Started/getting-started.md	Adds internal hyperlinks to related documentation, replaces UUID references with W3ID terminology, updates service descriptions to reference Registry and Ontology pages, and links key concepts (MetaEnvelope, Bearer tokens, key binding certificates).
Cross-linked W3DS Basics & Protocol Pages docs/docs/W3DS Basics/W3ID.md, docs/docs/W3DS Basics/getting-started.md, docs/docs/W3DS Protocol/Authentication.md, docs/docs/W3DS Protocol/Signing.md, docs/docs/W3DS Protocol/Signature-Formats.md, docs/docs/W3DS Protocol/Awareness-Protocol.md	Converts plain references to Markdown links for eVault, Registry, eID Wallet, and Ontology; updates session identifier terminology from UUID to cryptographically secure 128-bit session ID; standardizes namespace generation descriptions.
Cross-linked Post Platform Guide docs/docs/Post Platform Guide/getting-started.md, docs/docs/Post Platform Guide/mapping-rules.md, docs/docs/Post Platform Guide/webhook-controller.md	Adds links to Authentication, Signing, eVault, Registry, Ontology, and Web3 Adapter docs; updates schemaId references from UUID to W3ID format; expands References sections with linked resources.
Docusaurus Configuration & Navigation docs/docusaurus.config.ts, docs/src/pages/index.tsx, README.md	Updates production URL to https://docs.w3ds.metastate.foundation, changes favicon to W3DS logo, updates navbar label from "Tutorial" to "Docs", expands footer links to include W3DS Basics, Infrastructure, and Links; modifies home page redirect to respect baseUrl configuration and updates page metadata.
Category Navigation docs/docs/Getting Started/_category_.json, docs/docs/Post Platform Guide/_category_.json, docs/docs/W3DS Basics/_category_.json, docs/docs/W3DS Protocol/_category_.json	Removes generated-index link metadata from category configuration files while retaining position and label fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related issues

• [question] Registry documentation 🧐 #109: The new Registry.md documentation directly addresses protocol concerns by detailing endpoints (/resolve, /entropy, /.well-known/jwks.json) and cross-linking Registry behavior throughout the documentation.

Possibly related PRs

• docs: add infrastructure, protocol, and getting started docs #721: Overlapping documentation changes in Getting Started, eVault, eID-Wallet, Registry, and related infrastructure docs.
• Fix/dreamsync recommendations #691: Both PRs modify docs/src/pages/index.tsx for redirect logic and metadata updates.
• docs: add docs for key delegation and auth #720: Both PRs modify authentication and eVault-Key-Delegation documentation with cross-references and terminology updates.

Suggested reviewers

• xPathin
• sosweetham
• JulienAuvo

Poem

🐰 Hops through the docs with glee,
Cross-links now guide discovery,
W3IDs dance, no UUIDs here—
The Registry's mirror, crystal clear,
A foundation of knowledge, anchored and neat,
Documentation's heart, now complete! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Docs/ontology and registry' is concise and directly references the main additions (ontology and registry documentation), aligning with the substantial changes across multiple docs.
Description check	✅ Passed	The PR description follows the required template with all key sections: change description, issue number, type of change, and completed checklist items.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/ontology-and-registry

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/docs/Post Platform Guide/getting-started.md (1)

64-85: ⚠️ Potential issue | 🟠 Major

Fix the auth request body to use w3id as the user identifier (and drop the eVault URL).

The example shows w3id as an eVault URL and also includes ename. This conflicts with the signing/verification flow that identifies users by w3id (eName). Use w3id as the identifier and remove the redundant ename. Based on learnings, the correct parameter name is w3id for user identification.

✅ Suggested doc correction

-{- "ename": "@user.w3id",- "session": "abc123...",- "w3id": "https://evault.example.com/users/123",- "signature": "z..."-}+{+ "w3id": "@user.w3id",+ "session": "abc123...",+ "signature": "z..."+}

- const { ename, session, signature } = req.body;+ const { w3id, session, signature } = req.body;
// Verify signature using signature-validator ...
const verificationResult = await verifySignature({
- eName: ename,+ eName: w3id,
signature: signature,
payload: session,
registryBaseUrl: process.env.PUBLIC_REGISTRY_URL,
});
- const user = await this.userService.findUser(ename);+ const user = await this.userService.findUser(w3id);

Also applies to: 76-99

🤖 Fix all issues with AI agents

In `@docs/docs/Post` Platform Guide/mapping-rules.md:
- Line 16: The examples are inconsistent: the top example uses "schemaId":
"global_schema_w3id" while later examples use UUIDs; update the examples that
set "schemaId" (the example occurrences that currently use
"550e8400-e29b-41d4-a716-446655440000") to match the W3ID format used in the
basic structure, or alternatively add a short clarifying sentence after the
basic structure explaining that "schemaId" may be either a W3ID (e.g.,
"global_schema_w3id") or a UUID and show both example variants; locate and edit
the example blocks that define schemaId to ensure consistent formatting or add
the explanatory note.
In `@docs/docs/W3DS` Protocol/Awareness-Protocol.md:
- Around line 28-29: The anchor link targeting fromGlobal is broken: update the
link target (currently pointing to /docs/Infrastructure/Web3-Adapter#fromGlobal)
by either adding a dedicated heading "fromGlobal" (e.g., create a `###
fromGlobal` section so the anchor exists) in the Web3-Adapter document where the
fromGlobal function is discussed, or change the reference to an existing,
specific section such as `#receiving-data-inbound` where fromGlobal is covered;
ensure the Markdown heading text matches the anchor slug so the link resolves.

🧹 Nitpick comments (2)

docs/docs/W3DS Protocol/Signature-Formats.md (1)

324-324: Consider clarifying "unique identifier" terminology.

The change from "Create a UUID v4 for the namespace identifier" to "Create a unique identifier for the namespace" makes the terminology more generic. While this provides flexibility, it may leave readers uncertain about what format to use.

Consider either:

1. Keeping the UUID v4 specificity if that's the expected format, or
2. Adding a brief note about acceptable formats (e.g., "such as a UUID v4")

📝 Optional clarification

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a unique identifier for the namespace (e.g., UUID v4)

or, if any unique identifier is acceptable:

 2. **Generate Namespace**
- - Create a unique identifier for the namespace+ - Create a globally unique identifier for the namespace (such as UUID v4 or similar)

Also applies to: 329-329

docs/docs/W3DS Protocol/Authentication.md (1)

91-101: Align the reference snippet with the “session ID” terminology.

The text avoids UUID wording, but the example still uses uuidv4() and session. Consider renaming to sessionId and using a generic cryptographically secure generator (or add a short note that UUIDv4 is an acceptable 128‑bit session ID). This keeps terminology consistent and reduces reader confusion.

💡 Possible doc tweak

- const session = uuidv4();- const offer = `w3ds://auth?redirect=${url}&session=${session}&platform=blabsy`;+ const sessionId = crypto.randomUUID(); // 128-bit session ID+ const offer = `w3ds://auth?redirect=${url}&session=${sessionId}&platform=blabsy`;

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 49-52: The docs configuration's editUrl is pointing to the wrong
repository; update the docs.editUrl string in docusaurus.config.ts to the
correct GitHub repository path for this project (replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.
In `@docs/src/pages/index.tsx`:
- Around line 11-14: Normalize siteConfig.baseUrl to always end with a trailing
slash and avoid history.push on the homepage to prevent back-button loops: in
the useEffect referencing siteConfig.baseUrl and history.push, compute a safe
baseUrl (ensure it defaults to '/' and appends a '/' if missing), only run the
redirect when the current location pathname is the root (so you don't redirect
from nested pages), and use history.replace instead of history.push to perform
the navigation to `${baseUrl}docs/Getting%20Started/getting-started`; update
references to useEffect, siteConfig.baseUrl, and history.replace/history.push
accordingly.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Edit URL points to the wrong repository.
This appears to target a different repo name, which will break “Edit this page” links.

🔧 Proposed fix

- editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',+ editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',

📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	docs: {
	sidebarPath: './sidebars.ts',
	// Please change this to your repo.
	// Remove this to remove the "edit this page" links.
	editUrl:
	'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
	editUrl: 'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/',
	},
	docs: {
	sidebarPath: './sidebars.ts',
	editUrl: 'https://github.com/MetaState-Prototype-Project/prototype/tree/main/docs/docs/',
	},

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 49 - 52, The docs configuration's
editUrl is pointing to the wrong repository; update the docs.editUrl string in
docusaurus.config.ts to the correct GitHub repository path for this project
(replace
'https://github.com/MetaState-Prototype-Project/metastate/tree/main/docs/docs/'
with the proper repo URL for the current project) so the "Edit this page" links
resolve correctly; ensure the new URL points to the docs folder/branch used by
this site.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/docusaurus.yml:
- Line 4: The workflow currently triggers on pull_request which allows the
deploy job to run for PRs; modify the deploy job (named "deploy" in the
docusaurus.yml) to skip runs on PR events by adding a job-level condition such
as checking the event name or branch (e.g., add an if condition like
github.event_name != 'pull_request' or require github.ref == 'refs/heads/main'
&& github.event_name == 'push') so deploy only runs on real pushes to the
production branch; apply the same guard to the other affected deploy-related
jobs referenced around the block noted (lines 39-57) to prevent accidental PR
deployments.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/docusaurus.config.ts`:
- Around line 23-28: The projectName value in the Docusaurus config is
incorrect; update the projectName symbol in the configuration (currently set to
'metastate') to 'prototype' so deploy scripts that rely on projectName (e.g.,
the GIT_USER yarn deploy flow referenced in docs/README.md) will target the
correct GitHub repo; leave organizationName unchanged and run a quick deploy
dry-run to confirm settings.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash# Look for Docusaurus deploy / gh-pages usage and repo configurationecho"=== Searching for deploy references ==="
rg -n "docusaurus deploy|gh-pages|npm run deploy|yarn deploy|pnpm deploy" --max-count=20
echo -e "\n=== Checking package.json for deploy scripts ==="if [ -f"package.json" ];then
cat package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" package.json ||echo"No deploy scripts found"fiecho -e "\n=== Checking docs/package.json ==="if [ -f"docs/package.json" ];then
cat docs/package.json | jq '.scripts | select(.deploy or .gh)'2>/dev/null || grep -A 5 -B 5 "deploy\|gh-pages" docs/package.json ||echo"No deploy scripts found"fiecho -e "\n=== GitHub workflows related to docs ==="if [ -d".github/workflows" ];then
find .github/workflows -name "*.yml" -o -name "*.yaml"| head -20
fiecho -e "\n=== Repository name from git config ==="
git config --get remote.origin.url ||echo"Not a git repo"

Repository: MetaState-Prototype-Project/prototype

Length of output: 1398

---

🏁 Script executed:

#!/bin/bash# Examine docusaurus.config.ts to see full contextecho"=== Full docusaurus.config.ts (first 50 lines) ==="
head -50 docs/docusaurus.config.ts
echo -e "\n=== Checking for baseUrl and deploying related config ==="
rg -n "baseUrl|organizationName|projectName|url:" docs/docusaurus.config.ts -A 1 -B 1

Repository: MetaState-Prototype-Project/prototype

Length of output: 1993

---

🏁 Script executed:

#!/bin/bash# Look for any GitHub Actions workflows that might handle docs deploymentecho"=== Looking for docs-related workflows ==="
find .github/workflows -type f \( -name "*.yml" -o -name "*.yaml"\)2>/dev/null |whileread file;doecho"File: $file"if grep -q "docs\|docusaurus\|gh-pages""$file";thenecho"--- Content ---"
cat "$file"echo""fidone

Repository: MetaState-Prototype-Project/prototype

Length of output: 1817

---

Update projectName to match the actual repository name.

Line 28 sets projectName to 'metastate', but the repository is prototype. While the GitHub workflow bypasses docusaurus deploy and uses GitHub Pages directly, the docs/README.md instructs users to run GIT_USER=<username> yarn deploy, which relies on these settings. Running the deploy script would attempt to push to the wrong repository. Change projectName to 'prototype'.

🤖 Prompt for AI Agents

In `@docs/docusaurus.config.ts` around lines 23 - 28, The projectName value in the
Docusaurus config is incorrect; update the projectName symbol in the
configuration (currently set to 'metastate') to 'prototype' so deploy scripts
that rely on projectName (e.g., the GIT_USER yarn deploy flow referenced in
docs/README.md) will target the correct GitHub repo; leave organizationName
unchanged and run a quick deploy dry-run to confirm settings.

[nsergey82]

would be really nice if we had at least one example of each type somewhere. E.g., I have no idea from the top of my head how a "ledger" meta envelope may look like

[coodos]

@nsergey82 for these examples I imagine the better place would be the ontology viewer and not the docs, as then the docs may start to get more bloated.

[nsergey82]

not any w3ids, just the ename (according to out definitions)?

[nsergey82]

does it actually verify tokens, or merely provide us with material needed for such verification on our side?

[nsergey82]

this is obviously one of the candidates for pagination, but also rate limiting

[coodos]

pagination for this is being added