The Z00Z website repository is organized around a public documentation product. It contains Next.js source, Markdown content, a whitepaper corpus, configuration, developer scripts, planning artifacts, and local automation rules. It does not contain every future protocol runtime surface. That distinction is the main workspace habit to learn: local site behavior is proved by this repo; broader protocol architecture is proved by the corpus.

Use this page as a map before making changes. Most mistakes in this repository come from putting a change in the wrong layer or writing a claim as if a target subsystem were already present locally.

Repository Shape

The current repo uses the standard source locations below:

There is no top-level app/ source directory. Application routes live under src/app/. Do not place React, TypeScript, hooks, or application logic under public/.

Content-To-Route Model

The docs site is generated from a content tree and an existing loader. A Markdown file under content/docs/ normally maps to a /docs/... route. A section’s _meta.yaml controls ordering and section metadata. Frontmatter controls the page title, description, difficulty, icon, TOC behavior, and other page-level signals.

This model matters because most docs work should not add routes manually. If a page belongs in the docs tree, create or edit the Markdown file, keep _meta.yaml aligned, and let the existing loader resolve it.

Markdown And Rendering Boundary

src/lib/content/markdown.ts is the local authority for Markdown rendering features. It wires the markdown-it pipeline and the installed @mdit/* plugin family, including alerts, containers, tabs, footnotes, snippets, task lists, Mermaid handling, and TOC support. src/lib/content/docs.ts then reads frontmatter with gray-matter, resolves _meta.yaml, derives landing cards, extracts TOC items, rewrites content links, and loads domain pages.

That means a contributor should ask two different questions:

Do not add a second Markdown renderer, a parallel docs route, or a separate metadata authority for ordinary docs work. Phase 002 specifically reuses the current loader and route architecture.

Configuration And Scripts

The config/ directory holds site and content-pipeline inputs. The scripts/ directory holds executable local automation. The most important first-session scripts are exposed through package.json:

If you document a command, it should appear in package.json or an actual script file. If you need a command that does not exist, that is implementation work, not documentation wording.

Planning And Instruction Surfaces

.planning/ contains phase plans, state, roadmap, summaries, and review logs. Treat it as execution evidence. Do not delete or rewrite planning artifacts casually. For GSD work, the plan file defines the scope and verification gates for the current lane.

.github/ contains the local automation and instruction layer:

These files are local evidence for workflow claims. They are not a reason to publish private prompt internals. Public docs should describe the supported workflow at the right level: which surfaces exist, what they are for, and how they protect the repository from drift.

Where Not To Put Things

The fastest workspace mistakes are placement mistakes:

This boundary keeps the repository understandable. It also prevents concept drift where the docs start describing a second product structure that the codebase does not have.

Local Versus Target Architecture

The workspace has three evidence levels:

1. Live local repo evidence: Files and commands that exist here, such as package.json, scripts/verify.sh, src/lib/content/docs.ts, src/lib/content/markdown.ts, and src/app/api/dev/content-version/route.ts.
2. Corpus-backed architecture: Protocol concepts defined in content/whitepapers/, such as wallet-local possession, checkpoint settlement, assets, vouchers, rights, privacy boundaries, and post-quantum migration.
3. Open or target work: Surfaces the papers describe as future, proposed, optional, or not fully local here.

When writing developer docs, keep those levels visible. For example, this repository can prove the website route and content loader. It can explain the conceptual API families a future protocol implementation must expose. It should not pretend that the website repo ships every core protocol API, wallet SDK, RPC transport, or cryptographic runtime.

Practical Reading Path

If you are new to the workspace, use this path:

1. Open package.json and scripts/verify.sh to understand local commands.
2. Open Get Started for the first-session flow.
3. Inspect content/docs/developers/_meta.yaml for developer route order.
4. Read src/lib/content/docs.ts and src/lib/content/markdown.ts before changing content loading or Markdown behavior.
5. Read the relevant whitepaper before adding protocol, wallet, privacy, legal, or crypto claims.
6. Run npm run verify before closing the work.

This sequence is intentionally boring. It keeps builders aligned with the actual repo instead of forcing them to infer structure from stale page names or prior planning notes.

Read Next

Continue to Core Protocol API for the protocol object vocabulary, or read AI Agent Playbook for automation-specific workflow rules. Use Get Started when you need the command loop again.

Evidence and Further Reading

• src/, src/app/, content/, config/, public/, scripts/, .planning/, and .github/ are the live repository surfaces summarized on this page.
• .github/copilot-instructions.md defines source placement, English-only artifacts, safe file operations, and verification expectations.
• .github/requirements/Z00Z_WEB_DESIGN_FOUNDATION.md defines canonical Next.js, React, Tailwind, asset, route, and UI architecture rules.
• src/lib/content/docs.ts and src/lib/content/markdown.ts define the current docs loading and Markdown rendering boundaries.
• Main Whitepaper section 12 defines the live-versus-target evidence split used when workspace docs distinguish this website repo from broader protocol architecture.