Docs/restructure diataxis

[1amKhush]

Description

Closes #43
This PR reorganizes the entire documentation site around the Diátaxis framework and integrates the Rust SDK documentation from rs-sdk/docs/. The restructure was done to improve navigation, separate reference material from procedural guides, and scope design documentation within each SDK rather than as a standalone section.

Key structural decisions:

• Payments split: API reference (overview.md) stays under Reference > TypeScript SDK. The 5 implementation guides (getting-started, server, client, rails, custom-rails) move to How-to > Payments.
• Design is SDK-scoped: No top-level Design section. The Rust SDK includes its own Design subsection (reference/rs-sdk/design), ported from rs-sdk/DESIGN.md. Future TS SDK or protocol-level design docs follow the same pattern.
• CEPs promoted: CEPs are now a top-level group under Reference instead of being buried under Specification > CEPs, improving discoverability.
• Git history preserved: All file moves use git mv for rename tracking.

Verification

• astro build passes with 0 errors — all 60 content pages built successfully
• All sidebar slugs verified to map to existing files
• Pagefind search index regenerated (3443 words indexed)
• prettier formatting applied

What changed

New top-level navigation:

├── Getting Started
├── Reference
│   ├── Specification (draft spec, CEP guidelines)
│   ├── CEPs (promoted to top-level for discoverability)
│   ├── TypeScript SDK (core, transports, components, payments API ref)
│   └── Rust SDK ← NEW (12 pages ported from rs-sdk/docs/)
├── How-to
│   ├── CVMI CLI (moved from top-level cvmi/)
│   └── Payments (implementation guides split from TS SDK)
└── Tutorials
    └── Client-Server Communication

[vercel]

@1amKhush is attempting to deploy a commit to the ContextVM's projects Team on Vercel.

A member of the Team first needs to authorize it.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the documentation site structure by introducing a /reference section (including new Rust SDK docs) and normalizing many doc/code examples, while also updating site navigation and internal links accordingly.

Changes:

• Added Rust SDK reference documentation under src/content/docs/reference/rs-sdk/*.
• Updated a large set of internal doc links (e.g., /spec/*, /ts-sdk/*) to new /reference/* paths.
• Updated Astro/Starlight navigation and various code examples for consistent quoting.

Reviewed changes

Copilot reviewed 57 out of 65 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/utils/docSource.ts	Normalizes string quotes in doc-source glob + slug derivation.
src/content/docs/ts-sdk/tutorials/client-server-communication.md	Normalizes code sample quoting.
src/content/docs/ts-sdk/transports/oversized-transfer.md	Updates internal links to /reference/* and normalizes code sample quoting.
src/content/docs/ts-sdk/transports/open-stream.md	Updates internal links to /reference/*, normalizes quoting, and table formatting.
src/content/docs/ts-sdk/transports/nostr-server-transport.md	Updates internal links to /reference/* and normalizes quoting in examples.
src/content/docs/ts-sdk/transports/nostr-client-transport.md	Updates internal links to /reference/* and normalizes quoting in examples.
src/content/docs/ts-sdk/transports/base-nostr-transport.md	Updates internal links to /reference/* and normalizes quoting in examples.
src/content/docs/ts-sdk/signer/private-key-signer.md	Normalizes quoting in examples.
src/content/docs/ts-sdk/signer/custom-signer-development.md	Normalizes quoting in examples + error strings.
src/content/docs/ts-sdk/relay/applesauce-relay-pool.md	Normalizes quoting in examples.
src/content/docs/ts-sdk/quick-overview.md	Updates internal links to /reference/*.
src/content/docs/ts-sdk/proxy/overview.md	Updates internal links to /reference/* and normalizes quoting in examples.
src/content/docs/ts-sdk/payments/server.md	Updates internal links/paths + normalizes quoting in examples.
src/content/docs/ts-sdk/payments/rails/lightning-nwc.md	Normalizes quoting in examples.
src/content/docs/ts-sdk/payments/overview.md	Updates internal links to /reference/* and normalizes quoting in examples.
src/content/docs/ts-sdk/payments/getting-started.md	Updates internal import paths + normalizes quoting in examples.
src/content/docs/ts-sdk/payments/custom-rails.md	Normalizes quoting in examples.
src/content/docs/ts-sdk/payments/client.md	Normalizes quoting in examples.
src/content/docs/ts-sdk/gateway/overview.md	Normalizes quoting in examples.
src/content/docs/ts-sdk/core/logging.md	Normalizes quoting in examples.
src/content/docs/ts-sdk/core/interfaces.md	Normalizes quoting in enum example.
src/content/docs/ts-sdk/core/encryption.md	Normalizes quoting in examples.
src/content/docs/ts-sdk/core/constants.md	Normalizes quoting in constants example.
src/content/docs/ts-sdk/core/common-tool-schemas.md	Updates internal links to /reference/* and normalizes quoting in examples.
src/content/docs/spec/ctxvm-draft-spec.md	Updates CEP links to /reference/*.
src/content/docs/spec/ceps/informational/cep-35.md	Updates spec links to /reference/*.
src/content/docs/spec/ceps/informational/cep-21.md	Updates spec links to /reference/*.
src/content/docs/spec/ceps/cep-8.md	Updates spec links to /reference/*.
src/content/docs/spec/ceps/cep-6.md	Updates spec links to /reference/*.
src/content/docs/spec/ceps/cep-41.md	Updates spec links to /reference/*.
src/content/docs/spec/ceps/cep-4.md	Updates spec links to /reference/*.
src/content/docs/spec/ceps/cep-24.md	Updates spec links to /reference/*.
src/content/docs/spec/ceps/cep-23.md	Updates spec links to /reference/*.
src/content/docs/spec/ceps/cep-22.md	Updates spec links to /reference/*.
src/content/docs/spec/ceps/cep-19.md	Updates spec links to /reference/*.
src/content/docs/spec/ceps/cep-17.md	Updates spec links to /reference/*.
src/content/docs/spec/ceps/cep-15.md	Updates spec links to /reference/*.
src/content/docs/reference/rs-sdk/transports.md	Adds Rust SDK low-level transports reference page.
src/content/docs/reference/rs-sdk/transport-modes.md	Adds Rust SDK transport modes reference page.
src/content/docs/reference/rs-sdk/stateless.md	Adds Rust SDK stateless mode reference page.
src/content/docs/reference/rs-sdk/server-transport.md	Adds Rust SDK native server guide page.
src/content/docs/reference/rs-sdk/rmcp.md	Adds Rust SDK RMCP integration page.
src/content/docs/reference/rs-sdk/proxy.md	Adds Rust SDK proxy page.
src/content/docs/reference/rs-sdk/overview.md	Adds Rust SDK overview page.
src/content/docs/reference/rs-sdk/gateway.md	Adds Rust SDK gateway page.
src/content/docs/reference/rs-sdk/encryption.md	Adds Rust SDK encryption page.
src/content/docs/reference/rs-sdk/discovery.md	Adds Rust SDK discovery page.
src/content/docs/reference/rs-sdk/design.md	Adds Rust SDK design/architecture page.
src/content/docs/reference/rs-sdk/client-transport.md	Adds Rust SDK native client guide page.
src/content/docs/index.mdx	Updates homepage cards/links and adds Rust SDK card.
src/content/docs/getting-started/quick-overview.md	Updates getting-started links to new /reference/* layout and mentions Rust SDK.
src/content/docs/cvmi/overview.md	Updates CVMI links to /how-to/*.
src/content/docs/cvmi/installation.md	Updates CVMI links to /how-to/*.
src/content/docs/cvmi/commands.md	Updates CVMI links to /how-to/*.
src/content.config.ts	Normalizes import quoting.
astro.config.mjs	Restructures sidebar into Reference/How-to/Tutorials and updates slugs to /reference/*.
.github/workflows/deploy-github-pages.yml	Normalizes env var quoting.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[1amKhush]

p.s. The above flagged issues are false positives. it is incorrectly interpreting the Git rename syntax in the diff.
The files were moved using git mv to preserve git history, which shows up in the diff as {old => new} (e.g., src/content/docs/{spec => reference}/spec/ctxvm-draft-spec.md). The spec and ts-sdk files have actually been moved to their new reference/ and how-to/ paths.
I have verified the routing locally using astro build, which strictly validates the Starlight sidebar config. The build succeeds with 0 broken links and 404s. Furthermore, the absolute GitHub URL in index.mdx is intentionally pointing to the new paths on master, which will properly resolve as soon as this PR is merged.

[1amKhush]

@ContextVM-org Up for review!

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
contextvm-docs	Ready	Preview, Comment	Jun 10, 2026 3:25pm

[ContextVM-org]

This looks great, @1amKhush! I just have a few notes about the docs. The Rust "Architecture & Design" section doesn’t feel quite right, it feels like an LLM copypasta. Instead, we should describe how the Rust SDK is built. We can defer creating that document for now.

On the other hand, we could create more tutorials or guides for other common topics, such as:

• "Build a Public Server" explaining cep-6
• "Server & Client Using the Rust SDK"
• Other key tutorials or how-tos.

Overall, it’s looking really good! It would also be great to create an agents.md file that outlines the structure of the docs and the framework/mental model used to organize them. This way, future iterations can keep the documentation consistent.

[ContextVM-org]

Looks great, just some polishements.
Remove imaginary stuff:
/tutorials/build-a-public-server/:
'''

Example using an imaginary Nostr CLI

nostr-cli query --kinds 11316 --authors --limit 1
'''
Also instead of a copy paste of the cargo.toml in /tutorials/rust-server-client/
'''
Add the necessary dependencies to your Cargo.toml:
'''
Use actual cargo commands to install deps.
Also avoid using the damus relay as example. Use cvm relays or primal one which doesn't ratelimit as hard as damus