Documentation Standard

0x0 documentation is part of the implementation discipline. A behavior is not

finished when it merely works once; it must be findable, explainable, and guarded

by the same self-host checks as the code.

Documentation Map

• README.html: current user-facing state, quickstart, and project boundaries.
• docs/language.html: implemented language syntax and semantics.
• docs/compiler.html: compiler pipeline, backend architecture, ABI, and gates.
• docs/compiler-memory.html: production memory ownership, budgets, measurement,

and release report rules.

• docs/compiler-pipeline.html: phase-by-phase compiler ownership contract.
• docs/release.html: v0.1.0 release artifact boundary.
• docs/editors.html: LSP, Neovim, Zed, and Tree-sitter setup.
• docs/packages.html: package manifest, lockfile, and local path dependency

rules.

• docs/index-kukulkan-production-roadmap.html: staged plan for replacing Index

and Kukulkan with production 0x0 applications.

• docs/index-kukulkan-real-production-rewrite-roadmap.html: strict production

rewrite plan that rejects constructor-only, demo, fixed-response, and draft

completion signals.

• docs/public-docs-website-roadmap.html: public documentation, static website,

library registry, and jmp0x1b/lang obsolescence migration plan for making

0x0 the current public language surface.

• docs/public-docs-gap.html, docs/public-docs-source-map.tsv,

docs/public-site-map.html, docs/safe-public-docs-gates.html, and

docs/static-sites-remote-inventory.html: Milestone 0 inventory, route,

safety, and read-only remote-site baseline for public documentation migration.

• site/: public static documentation source for 0x0.jmp0x1b.com, including

Start, Learn, Build, Reference, Cookbook, Tasks, Libraries, Migration,

Release, and Embedded Status entry points.

• site/learn-0x0/: complete 15-lesson public Learn 0x0 course and lesson map

for implemented language, package, runtime, app, release, and migration

behavior.

• docs/grammar.ebnf, docs/syntax.html, docs/language-spec.html,

docs/package-system.html, docs/api-cross-reference.html,

docs/capabilities.html, and docs/migration-policy.html: public reference

layer for implemented syntax, language, package, API, capability, runtime, and

migration behavior.

• docs/style-guide.html, docs/lint.html, docs/lint-rule-catalog.tsv,

docs/safe-commands.html, docs/standalone-libraries.html,

docs/contributing.html, and docs/ai-contributing.html: public best-practice,

lint, safe-command, standalone library, and contribution guidance.

• site/cookbook.html, site/cookbook-inventory.tsv,

docs/public-recipe-map.html, and tools/public-cookbook-check.sh: public

recipe inventory, cookbook, and task-oriented validation for current examples,

libraries, runtime boundaries, and app docs.

• libs/registry.tsv, libs/aliases.tsv, libs/deprecations.tsv,

libs/smoke-evidence.tsv, site/libs/, and

docs/libs-registry-inventory.html: generated static registry metadata and

pages for 0x0 libraries.

• docs/jmp0x1b-lang-obsolescence.html,

docs/jmp0x1b-to-0x0-command-map.html,

docs/jmp0x1b-to-0x0-syntax-migration.html,

docs/jmp0x1b-to-0x0-package-migration.html,

docs/feature-support-matrix.html, and

docs/public-domain-migration-plan.html: top-level migration and obsolescence

references for replacing jmp0x1b/lang and updating public domains.

• docs/public-site-style.html, docs/public-site-build.html, and

tools/public-site-build.sh: static site styling and local build contract for

the public documentation portal.

• docs/apps-real-production-gap.html, apps/real-rewrite-gap.tsv, and

apps/real-rewrite-target-map.tsv: strict production rewrite gap inventory

for constructor-only app source, Python release shims, checker-owned behavior,

fake adapters, and fixed-response paths.

• docs/apps-production-build.html, apps/build-manifest.tsv,

apps/index/release/production-manifest.tsv, and

apps/kukulkan/release/production-manifest.tsv: deterministic 0x0

source-package build path that excludes checker code and Python release shims

from production app artifacts.

• docs/runtime-production-capabilities.html,

runtime/production-capabilities.tsv, runtime/production-host.0x0, and

tools/production-host-runtime.py: production host runtime boundary for

local effects, HTTP/browser capture, server/Live behavior, and service

adapters used by the real app rewrite.

• apps/accepted-behavior-corpus.tsv,

apps/intentional-behavior-differences.html, and

apps/*/tests/accepted-corpus.0x0: executable migrated app corpus tests that

import app source through the production source-package path.

• docs/apps/: generated Index and Kukulkan replacement inventories and

dependency matrices.

• apps/: generated application workspace manifests, parity manifests, and

package/test discovery metadata for the Index and Kukulkan replacement work.

• docs/apps/porting-style.html: source rewrite naming, capability, constructor,

and runtime-boundary conventions for the Index and Kukulkan app ports.

• apps/porting-scan.tsv, apps/fixture-conversion.tsv,

apps/parity-runner.tsv: generated porting harness artifacts used by

make source-rewrite-foundation-check.

• docs/apps/resource-safe-gates.html: safe docs, app compile, and runtime

process hygiene gates for long-running app replacement work.

• apps/runtime-ports.tsv: app-owned runtime ports and PID files used by

make apps-runtime-hygiene-check.

• docs/runtime-capabilities.html, runtime/capabilities.tsv, and

abi/runtime-calls.tsv: host runtime capability taxonomy and ABI call matrix

for app runtime boundaries.

• runtime/app-host.0x0 and runtime/app-host-fake.0x0: production and

deterministic fake 0x0-facing app host runtime contracts.

• docs/local-effects-runtime.html, runtime/local-effects.tsv,

runtime/local-effects.0x0, and runtime/local-effects-fake.0x0: local

filesystem, CLI/environment, and subprocess runtime contracts.

• docs/fetch-browser-runtime.html, runtime/fetch-browser.tsv,

runtime/fetch-browser.0x0, and runtime/fetch-browser-fake.0x0: HTTP

client, browser snapshot, and capture redaction runtime contracts.

• docs/web-runtime.html, runtime/web-runtime.tsv, runtime/web-runtime.0x0,

and runtime/web-runtime-fake.0x0: HTTP server, router, WebSocket, and

LiveView-compatible runtime contracts.

• docs/service-boundary-runtime.html, runtime/service-boundary.tsv,

runtime/service-boundary.0x0, and runtime/service-boundary-fake.0x0:

database, auth/OIDC, service adapter, backup/restore, and job runtime

contracts.

• docs/index-pure-rewrite.html, apps/index/pure-surfaces.tsv, and

apps/index/src/*.0x0: pure Index document, extraction, rendering, and

policy-tool source surfaces.

• docs/index-runtime-replacement.html, apps/index/release/bin/index, and

apps/index/release/manifest.tsv: Index CLI runtime entrypoint and package

release metadata.

• docs/kukulkan-pure-packages.html, apps/kukulkan/pure-surfaces.tsv, and

apps/kukulkan/packages/*/src/lib.0x0: pure Kukulkan package surfaces for API

contracts, client requests, events, compliance, geospatial, service-stack, and

SaaS orchestration domains.

• docs/kukulkan-api-runtime.html,

apps/kukulkan/packages/kukulkan_api_runtime/src/lib.0x0, and

apps/kukulkan/packages/kukulkan_api_runtime/release/bin/kukulkan-api:

Kukulkan API runtime boundary, loopback API process, and runtime probes.

• docs/kukulkan-ui-runtime.html,

apps/kukulkan/packages/kukulkan_web_ui/src/lib.0x0, and

apps/kukulkan/packages/kukulkan_web_ui/release/bin/kukulkan-web: Kukulkan

UI, LiveView-compatible, browser bridge, and quality report runtime probes.

• docs/kukulkan-deployment.html and apps/kukulkan/deploy/: Kukulkan

dependency profiles, image specs, Helm/Kubernetes templates, systemd units,

and remote deployment command plans.

• docs/apps-production-replacement.html,

docs/kukulkan-operator-runbook.html, apps/cutover-matrix.tsv, and

apps/release-candidate/: final Index and Kukulkan production replacement

cutover, release-candidate, acceptance, and operator runbook artifacts.

• docs/frameworks.html: source-level framework/library layers above core

runtime primitives.

• docs/maintainer-manual.html: command map, workflows, and debugging guide for

continuing the project without outside assistance.

• docs/roadmap.html: maturity path and release sequencing.
• docs/features/: feature planning notes created by tools/new-feature.sh.
• docs/bootstrap.html: bootstrap model and command flow.
• docs/constitution.html: project laws.
• docs/history.html: historical bootstrap note.
• compiler/main.0x0: canonical compiler source with section comments for

invariants and backend/runtime boundaries.

• compiler/compat-main.0x0: compatibility compiler source used to build

zero-native, including the optional C and legacy object assembly paths.

• tools/doccheck.0x0: executable documentation policy written in 0x0.
• tools/doccheck.sh: file discovery wrapper for the 0x0 documentation policy.
• tools/docgen.0x0: executable API documentation generator written in 0x0.
• tools/docgen.sh: generation/check wrapper for docs/api.html.
• tools/pkg-lock.0x0: executable package manifest validator and lockfile

generator written in 0x0.

• tools/pkg-lock.sh: generation/check wrapper for 0x0.lock.
• tools/zero-lsp.py: host-side LSP shim that delegates diagnostics to 0x0.
• tools/doctor.sh: quick/full/release maintainer gates.
• tools/memory-check.sh: peak-RSS release compiler budget gate.
• tools/new-feature.sh: feature-plan scaffold.
• tools/new-example.sh: example scaffold.
• editors/: editor integration source files.
• examples/*.0x0: executable language examples. Each example should state the

feature it exercises and the expected observable result.

• perf/memory-budgets.txt: enforced peak-RSS budgets.
• perf/memory-baselines/: release baseline measurements.

Markdown Rules

Markdown docs must describe what the repository actually implements today.

• Prefer concrete commands, file paths, and invariants over broad claims.
• Keep future work in limitation sections, not in feature descriptions.
• When a command is a gate, include the expected success condition.
• When an ABI, tag, binary layout, or bootstrap rule changes, update the

compiler guide in the same change.

• Do not document placeholder APIs, planned modules, or fake backends as if they

exist.

0x0 Source Comment Rules

0x0 uses line comments beginning with ;.

Use this convention:

;;; File or major section comment.
;; Function group, invariant, ABI, or algorithm note.
; Local note for a line or small block.

Use source-level doc annotations for public functions in libraries and

frameworks:

(ƒ add
  (∷ (→ I64 I64 I64))
  (doc "Return the sum of two integers.")
  (a b)
  (+ a b))

The compiler skips doc annotations the same way it skips type annotations.

That makes documentation part of the language surface without changing emitted

OISA, C, or ELF behavior.

Comments should explain:

• Representation choices such as tagged AST nodes or runtime value tags.
• Bootstrap boundaries and why a backend exists.
• ABI rules, stack/register conventions, byte layouts, and syscall assumptions.
• Non-obvious control flow or fixed-point layout algorithms.
• The intent of examples and the expected observable output.

Comments should not:

• Restate the syntax of the next expression.
• Describe implementation details that are obvious from one line of code.
• Promise behavior that is not covered by examples, tests, or self-host gates.
• Hide technical debt. If a limitation matters, name it directly.

Required Updates

Every compiler, backend, runtime, or language change must include at least one of

these documentation actions:

• Update docs/language.html for source behavior.
• Update docs/compiler.html for pipeline, runtime, ABI, or emitted artifact

behavior.

• Update docs/compiler-memory.html and docs/compiler-pipeline.html for compiler

allocation, retention, layout, emission, or measurement behavior.

• Update docs/bootstrap.html for seed, stage, or command flow behavior.
• Update source comments in compiler/main.0x0 when an invariant changes.
• Update an example comment or add an example when the observable language slice

grows.

Small internal cleanups may not need Markdown changes, but they still must not

make existing docs false.

Enforced Rules

The legacy broad documentation gate is:

make docs-check

That command is not a safe default for public documentation migration work until

its resource behavior is bounded. Use the public-docs milestone gates for this

roadmap:

make public-docs-milestone-0-check
make public-site-link-check

make docs-check remains part of tests/smoke.sh and the broader repository

verification path, but it must not be used as the default public docs migration

gate while it can break the user session.

The current policy enforces:

• Every .0x0 source file must have top-of-file documentation, either ;;; or a

top-level doc form near the top.

• Every .0x0 source file must avoid raw tab and carriage-return characters.
• Every .0x0 source file must end with a newline.
• Every .0x0 source line must avoid trailing spaces.
• Indentation must use two-space steps.
• Every .0x0 source file must have balanced parentheses, ignoring parentheses

inside strings and comments.

• Every example must document its expected output.
• compiler/main.0x0 must retain named section docs for the OISA entry, shared

function metadata helpers, direct ELF backend, ELF ABI, and ELF serialization.

• Files under tools/, lib/, and frameworks/ must document every function

with either a preceding ;; comment or an inline (doc "...") annotation.

• docs/api.html must match the Markdown generated by tools/docgen.0x0.
• 0x0.lock must match the package lock generated by tools/pkg-lock.0x0.

Regenerate API docs after changing public library functions:

make docs-api
make public-site-link-check

Regenerate the package lock after changing 0x0.pkg:

make package-lock
make package-check

Review Standard

Before committing documentation-related work:

git diff --check
make public-docs-milestone-0-check
make public-site-link-check
make package-check
make editor-check
make memory-check
make doctor
make selfhost-guard

The public docs gates are the default for public documentation migration work.

The broader self-host gates still matter for source, comments, examples,

compiler behavior, and release work, but they are not the default quick path for

site and migration documentation changes.