Agent guide

Manteen is designed around inspectable plans, stable machine output, and source ownership that can survive local adaptation. An agent should be able to discover what exists, explain a refusal, and apply exactly the plan a person reviewed.

Check the installed surface

This contract was frozen while manteen@0.5.0 was public. The agent-native authoring and workflow foundation shipped in manteen-kit@0.2.1 and manteen@0.7.0; the machine-envelope work was an internal 0.6.0 milestone, not a separate package release. The complete behavior documented here is versioned for manteen@0.8.0. Documentation still is not proof of what a project has installed. Inspect manteen --version and command --help; never invent a command or flag that the installed binary does not expose.

Examples on this page use the logical command manteen. Resolve the project-installed binary with the declared package manager and disallow transient acquisition: npm exec --yes=false -- manteen, pnpm exec manteen, yarn manteen, or bunx --no-install manteen. Keep package-manager stderr separate from Manteen’s JSON stdout.

The operating model

1. Establish the project root and read its AGENTS.md or equivalent instructions.
2. Inspect manteen --version, then prefer manteen status --json when available.
3. Use list, info, and diff to understand registry and installed state before changing it.
4. Run every mutation with --dry-run --json first.
5. If the preview returns a planDigest, retain the exact refs, root, flags, and digest. Apply with the same command plus --expect-plan <digest>.
6. Treat destructive flags as separate user decisions, not retry strategies.
7. Parse stdout as one JSON document. Keep stderr separate.

JSON mode disables prompting; it does not grant overwrite or discard authority. A missing choice is supposed to remain a structured refusal.

An unqueried list retains deterministic registry and canonical item order. --query ranks rows within each registry by exact canonical id, exact name, exact title, title prefix, id/name substring, title substring, then description substring. Ties retain prior order, and JSON exposes both queryMatches and the winning queryRank.

Agent-oriented command surface

Command	Mode	Purpose	Agent contract
manteen init	write	Detect and configure a supported Mantine application.	0.6.0
manteen add	write	Resolve, plan, and install registry items.	0.6.0
manteen list	read	Discover configured registry items deterministically.	0.6.0
manteen info	read	Inspect one item's complete install and display metadata.	0.6.0
manteen diff	read	Compare local, pristine-base, and current upstream state.	0.6.0
manteen update	write	Three-way merge upstream changes around local adaptations.	0.6.0
manteen remove	write	Remove exact receipt-owned files proven absent upstream.	0.6.0
manteen status	read	Assess local project and receipt health without network access.	0.7.0
manteen agent guide	read	Print the packaged agent guide without project configuration.	0.7.0
manteen agent install	write	Safely install or update the packaged Manteen skill.	0.7.0

agentContract is the milestone where the stable agent-facing behavior is defined, not the first version in which the human command name existed.

Safe install and update loop

manteen info @house/article-card --json
manteen add @house/article-card --dry-run --json
manteen add @house/article-card --expect-plan <sha256> --json

manteen diff @house/article-card --json
manteen update @house/article-card --dry-run --json
manteen update @house/article-card --expect-plan <sha256> --json

An ordinary update performs a three-way merge around local source adaptations. --take-upstream means discard those adaptations. --overwrite, --discard-adapted, --no-verify, and --take-packaged likewise represent concrete consequences and should appear only after that consequence is chosen.

Do not edit manteen.lock.json or .manteen/bases/ by hand. Commit installed source, the receipt, and pristine bases together.

Installation is not application integration

manteen add installs registry-managed source and ownership state. It does not determine which application route should import, render, or otherwise use the item. If the request asks only for installation, do not invent a placement. If it asks to use the item, inspect manteen info usage and props, edit the appropriate consumer-owned application file, and run the project’s required checks. Report installation and application integration as separate facts.

Machine responses

The client schema version is 1. Every recognized --json invocation emits one envelope with:

schemaVersion, command, root, ok, exitCode, mutated,
payload, diagnostics, errors, notes

ok is exactly exitCode === 0. A successful offline status can still report healthy: false; that is an assessment, not a command failure. Blocking diagnostics include a typed rerun argv array, a configuration patch, or a bounded manual action/rationale.

Status health covers only Manteen’s local configuration and ownership state. It does not run the application’s typecheck, tests, or production build. Inspect configured verification and execute the project checks required for application-level proof.

Never expose an expanded environment placeholder from a registry URL. Only redacted URLs are safe in output, receipts, diagnostics, or plan digests.

Install the packaged skill

When the local version provides agent commands:

manteen agent guide --json
manteen agent install --dry-run --json
manteen agent install --json

The default project target is .agents/skills/manteen. Explicit universal-user, Codex-user, Claude-project, Claude-user, and custom targets are available. An unowned or locally modified installation is refused. --update updates an owned copy; --take-packaged explicitly discards its adaptation.

manteen init never installs the skill or edits project agent instructions implicitly.

For compact machine discovery, see llms.txt. For the complete static guide, see llms-full.txt.