Quickstart ​

The shortest verifiable path from an empty machine to a governed project. Installing the skill package does not create .tenetora/; initializing the project is a separate action.

Audience ​

Developers who want to run Tenetora with their coding agent and finish with proof: an effective installation, an initialized project record, and passing validation — not just a printed version string.

Task path ​

1. Install or upgrade the skill package through the gated entry below.
2. Verify the installation: version, status, doctor.
3. Initialize the project record with tenetora-init.
4. Validate the baseline: validate, run-all, audit, recap.
5. Route daily work through the lifecycle skills and action guards.
6. Register machine-only local environment paths with local-env, so doctor and the commit guard can watch them.
7. Keep the two update loops separate: package upgrade versus project .tenetora update.

Install or upgrade the package ​

The panel above is driven by the typed facts layer. While the public sources are unverified it shows the evidence state instead of a command — that is the intended fail-closed behavior, not a missing feature.

When the gate passes, the installer behaves as follows:

• An interactive terminal asks for English or Chinese first; automation pins the language with --lang or TENETORA_LANG.
• First install can create global, project, or both scopes.
• Re-running without a scope performs an existing-only upgrade: every registered global surface, project surface, and governance-only project is refreshed, and nothing new is created.
• Starting inside a governed project also runs bounded discovery of sibling .tenetora projects and proven legacy .harness directories.
• Capability results are FULL, PENDING_TRUST, PARTIAL, or BLOCKED; waiting for trust confirmation or a host restart is a successful state, and only real partial or blocked failures print detailed log paths.
• A global install provides the hook runtime only — governance is enabled explicitly per project. A workspace without .tenetora/ or a legacy .harness/ stays silent: no rule injection, no reminders, no commit gate, no external-input gate.

Once the CLI is installed, day-to-day upgrades use it directly — no remote script:

tenetora upgrade --check
tenetora upgrade
tenetora upgrade --force

--check shows the plan only; a plain upgrade performs the existing-only upgrade of registered surfaces. upgrade reads and authenticates the remote manifest first. When the published version matches the installed CLI it reports "already latest", skips the ZIP download and the install transaction, and exits successfully; --force exists only for re-converging the same version after a repair. Users arriving from 0.2.x cross the 0.3 bridge once with a version-pinned bootstrap, then use tenetora upgrade.

The machine registry keeps its own hygiene explicit:

tenetora installations --json list
tenetora installations --json prune --expired

list marks surfaces stale, and stale entries past the bounded retention window expired. prune --expired is never automatic: it removes machine-registry metadata only — never project directories, .tenetora, local environment files, or third-party configuration.

Preview what a scope-less upgrade would touch:

tenetora installations discover --auto --dry-run

Requirements: Python 3.9 or newer; native Windows uses the PowerShell installer (install.ps1) and requires neither Git Bash nor WSL; native plugin hosts need a restart after installation; Codex may need a trust review in /hooks. Offline ZIP install, preflight, reset, and troubleshooting live in the full installation guide shipped with the source repositories (linked from the navigation of every page).

Verify the installation ​

tenetora version
tenetora status --tools all --scope both --path . --verbose
tenetora doctor --tools all --scope both --path .

Success is more than a version string. status must name the effective source for each tool, and doctor must explain any trust, restart, inactive-runtime, or platform-limit follow-up. An attention state is actionable evidence; do not hide it by checking only the version.

If tenetora is not on PATH, use the absolute command returned by the current host skill's ensure_cli.py --install --json. Do not persist tool-local PYTHONPATH invocations or aliases.

Initialize the project ​

From an AI tool:

use tenetora-init to initialize .tenetora

CLI equivalent for an existing repository:

tenetora init --tools auto --write --gitignore yes --migrate plan --mode extract --defaults missing

Use --mode scaffold for an empty repository, and keep --entrypoints plan until migration and backup decisions are reviewed. Extracted facts carry source paths; inferences stay labeled; unknown architecture and commands are recorded as unknown, never invented.

Validate the baseline ​

tenetora validate --path .
tenetora run-all --path .
tenetora audit --strict --path .
tenetora recap --write --path .

validate proves the project record is structurally consumable. run-all proves the configured guardrails pass. audit reports quality and remaining governance findings. None of them replaces the repository's own build and test commands.

Before broad work, read .tenetora/README.md, .tenetora/changes/INDEX.md, and .tenetora/state/current-evidence.json — current guidance first, not the archive.

Upgrade the package and update the project separately ​

These are two independent loops, and neither substitutes for the other:

• Package upgrade refreshes skills, plugins, and runtime surfaces on the machine, using the installer entry above.
• Project update refreshes the governance content inside one repository's .tenetora/:

use tenetora-update to update .tenetora

After a package upgrade, check for known project repairs:

tenetora repair --check --path .

Installing skills never creates .tenetora/, and updating .tenetora never installs new skill surfaces.

Protect local environment files ​

Projects often depend on machine-only files — .env, local configuration, certificates — that must never enter Git or shared evidence. Register the project-relative path without storing any content:

tenetora local-env --path . --allow config/local/app.conf
tenetora local-env --path . --list --json

• tenetora status and tenetora doctor report a registered path that disappears and a damaged registry — read-only checks; file contents are never read.
• Commit guard treats registered paths as sensitive and keeps them out of the staging area.
• On hosts that supply a structured tool name and path, PreToolUse denies high-confidence destructive operations against registered paths; a host that cannot resolve both is never blocked speculatively.

Never commit a local environment file to satisfy a check — registration exists so those files stay local. Recovery starts from the project checkpoint, not from deleting files to pass a guard.

Daily high-risk boundaries ​

tenetora rules --context <context> --path .
tenetora guard --action commit --commit-message-file /path/to/commit-message.txt --require-message --path .
tenetora guard --action external-input --file /path/to/untrusted-input.txt --source "issue-report" --path .
tenetora guard --action claim --claim-kind completion \
  --session-id <session-id> --owner-id <owner-id> \
  --conversation-id <conversation-id> --tool <tool> \
  --verification-command "<full verification command>" --verification-status passed --path .

• A local check uses --claim-kind partial-verification; it cannot satisfy the completion gate.
• A completion claim must bind the current owner-bound alignment session and its goal fingerprint, repeat the identical command with --expected-verification-command, and the Git worktree must be unchanged.
• When the task cannot complete, record --claim-kind blocked or --claim-kind failed; never fabricate a passed proof.
• Continuing a task from another conversation never reuses its claim proof: inspect the owner-bound alignment session first, then claim again with the current session and conversation identities.

Alignment proof, claim proof, commit permission, and push permission are independent. No skill or hook grants commit, push, deploy, or release authorization by itself.

Limitations ​

• No recommended install command is offered while the public sources are unverified; commands copied from third-party posts are not authoritative.
• validate, run-all, and audit check governance health; they do not replace the project's own build and test commands.
• Guards check action boundaries and produce evidence; they never create authorization.
• PreToolUse protection needs structured host data; on skills-only hosts, commit guard plus doctor/status are the available layers.

Next steps ​

• Read Concepts for the governance model behind these commands.
• Check Integrations for your platform's required follow-up.
• Review Security for the external-input boundary.