Quickstart

PrerequisitesCopy Anchor Link

• A built numi from the install page. Commands below assume numi is on your path; substitute ./bin/numi or go run ./cli/numi otherwise.
• A clone of numinance-spec, for the example documents. Run step 1 from its root.
• A Python repository for step 2. A directory with a pyproject.toml is enough.

Step 1: validate the shipped examplesCopy Anchor Link

numi validate --files schemas/examples/SDLCProfile

revision: "files"
ok       file "org-baseline.yaml" SDLCProfile "org-baseline"
ok       file "payments-api.yaml" SDLCProfile "payments-api"

--files checks each YAML file against its generated kind schema and runs the loader checks. Unknown fields are errors unless they sit under extensions:. It runs no resolver and no floors. Point it at the whole schemas/examples directory and every example kind passes; add --json for one machine-readable object.

Step 2: scaffold a repositoryCopy Anchor Link

numi init --ci github-actions .

--ci is required, because a default CI system would wire one your repository may not use. The command detected uv from a pyproject.toml with no package-manager table.

numi init: repository "."
chose: package manager uv (detected from pyproject.toml with no package manager table, the default)
chose: python 3.12 (default)
chose: verifiers unit-tests lint typecheck (default)
chose: ci github-actions (flag)
chose: language python (default)
chose: scm github (default)
chose: tickets none (default)
wrote ".numinance/policy/sdlc-profile.yaml"
wrote ".numinance/policy/autonomy.yaml"
wrote ".numinance/policy/stage-registry.yaml"
wrote ".numinance/policy/playbook-bugfix-bounded.yaml"
wrote ".numinance/policy/toolchain-python.yaml"
wrote ".numinance/README.md"
autonomy: PR only (ladder level AUTONOMY_LEVEL_PR, no merge)
note: unit-tests (pytest) runs candidate code and is UNAVAILABLE in the live verifier provider until its nested sandbox exists
note: without --org-dir the stage registry is not selected and floors are the engine's shipped floors (PR; HIGH at SUGGEST)
next: numi validate "."

Each chose: line names a decision and where it came from: flag, default, or detected from <file>. The generated tree:

The agent level it chose is the cautious one: AUTONOMY_LEVEL_PR. It may open pull requests and may never merge. First configuration walks through each file.

Step 3: validate the resultCopy Anchor Link

numi validate .

revision: "working tree (uncommitted changes included)"
ok       repo ".numinance/policy/autonomy.yaml" AutonomyPolicy "pr-only"
ok       repo ".numinance/policy/playbook-bugfix-bounded.yaml" Playbook "bugfix-bounded"
ok       repo ".numinance/policy/sdlc-profile.yaml" SDLCProfile "python-repo"
ok       repo ".numinance/policy/stage-registry.yaml" StageRegistry "pr-only"
ok       repo ".numinance/policy/toolchain-python.yaml" LanguageToolchain "python-3.12"
numi validate: profile resolution needs the Numinance engine build

Why exit 7 is the expected resultCopy Anchor Link

All five documents are schema-valid. Exit 7 has exactly one meaning in the open build: the schema pass succeeded, and profile resolution is not available because it belongs to the Numinance engine build. The design is deliberate. A CI job that ran the open numi validate could otherwise report green on a configuration whose floors and bindings were never resolved.

If you want an exit code of 0 for the schema check alone, say so explicitly:

numi validate --files .numinance

This exits 0 with the same five documents shown as ok file .... Treat it as a lint, not as validation of the repository.

Step 4: re-run and meet exit 5Copy Anchor Link

numi init --ci github-actions .

numi init: .numinance already has files; pass --force to overwrite the files init writes (other files are never touched)

Exit 5 is a conflict. init will not overwrite your edits. --force overwrites only the files init itself writes; any other file in .numinance/ is left alone. Use it deliberately, since it discards local changes to the generated documents.

Failure modesCopy Anchor Link

Next stepsCopy Anchor Link