ONBOARDING.md

Onboarding

Welcome to the public N1Hub specification surface.

Step 1: Learn the shape

• Read README.md for the repository map.
• Read QUICKSTART.md if you need the shortest entry path.
• Read docs/audience-paths.md if you want the bounded role-specific path before diving deeper.
• Inspect PUBLIC_AUDIENCE_PATHS.json if you want the same contributor, reviewer, integrator, tool-builder, and maintainer lanes in machine-readable form.
• Read docs/repository-scope.md to understand what is intentionally excluded.

If you are here to contribute code or docs directly, continue with this file. If you are actually here to review, integrate, or build tooling against the public surface, jump to the narrower lane from docs/audience-paths.md instead of staying on the contributor path by default.

Step 2: Understand the rules

• Read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.
• Read GOVERNANCE.md to understand source-of-truth and review expectations.
• Read docs/community-health.md to understand the intended issue and PR intake paths.
• Read docs/repo-validation-workflow.md to see the repo-only command flow before opening a PR.

Step 3: Understand the public technical surface

• Read docs/schema-reference.md.
• Read docs/validator.md and docs/openapi.md.
• Read docs/api-envelopes.md and docs/compatibility.md.
• Inspect schemas/validator-api-envelopes.schema.json if you need a machine-readable validator envelope bundle.
• Read docs/integration-guide.md and VERSIONING.md before treating the repo as an integration dependency.
• Read docs/route-reference.md for the route-by-route validator map.
• Read docs/client-recipes.md and inspect examples/client/ for copyable consumer snippets.
• Read docs/npm-consumption.md if you want the buildable package-export path rather than only file-relative source imports.
• Read docs/trust-model.md before treating prose examples as stronger than schemas or the live validator.
• Read docs/contract-catalog.md and inspect PUBLIC_CONTRACT_CATALOG.json if you need a machine-readable public surface map.
• Read docs/release-evidence.md and inspect PUBLIC_RELEASE_METADATA.json if you need structured release evidence.
• Read docs/source-materials.md so projection provenance stays explicit.
• Compare the raw capsules in capsules/ with the machine-readable schemas in schemas/.
• Inspect docs/examples.md and examples/example-known-ids.json before changing graph-linked examples.

Step 4: Understand maintainership and roadmap

• Read MAINTAINERS.md.
• Read ROADMAP.md.
• Read CHANGELOG.md.

Step 5: Make the right kind of change

• Use small pull requests for docs, examples, schema corrections, and public-surface improvements.
• Open an issue first when a change would alter the capsule law, validator semantics, or public repository scope.
• Treat main as the stable public branch and dream as the public exploration branch for larger still-public work.
• Collapse proven dream work into smaller reviewable slices before landing it in main.
• Do not use either public branch for private operator material, local vault content, or maintainer-only exports.
• Run npm run verify:repo and refresh PUBLIC_RELEASE_REVIEW.md before proposing a release-facing change.
• Use docs/repo-validation-workflow.md for the narrow command packet that matches the change class before running the full repo pass.
• Read docs/verification.md if you need to interpret a failing repo-local check.
• Keep PUBLIC_RELEASE_METADATA.json and NOTICE aligned with release-facing changes.
• Keep client recipes aligned with API example payloads and route docs when HTTP surfaces change.
• Keep docs/npm-consumption.md, package.json, and tsconfig.build.json aligned with the maintained projection layer when the package-export surface changes.