Archkit Project System Guide

Archkit project system organizes authored models, generated artifacts, reports, and inspection workflows under one deterministic project root.

Project shape

my-project/
├── archkit.project.toml
├── authored/
├── overlays/
├── mirror/
├── promoted/
├── generated/
├── reports/
│   └── generate/
│       ├── project-generate.archkit.plan.json
│       └── project-generate.archkit.report.json
└── .archkit/index/

Core commands

Initialize project:

nix develop -c cargo run -p archkit-cli -- project init --root ./my-project --name "My Project"

Validate layout and health:

nix develop -c cargo run -p archkit-cli -- project layout-check --root ./my-project
nix develop -c cargo run -p archkit-cli -- project dogfood --root ./my-project

Self-Hosting Assessment (M1-M9)

Assess self-hosting adoption readiness using the complete meta-model foundation:

# Text report (human-readable)
nix develop -c cargo run -p archkit-cli -- project self-hosting-assess --root ./my-project

# JSON report (machine-readable)
nix develop -c cargo run -p archkit-cli -- project self-hosting-assess --root ./my-project --format json

# Save to file
nix develop -c cargo run -p archkit-cli -- project self-hosting-assess --root ./my-project --out adoption-report.txt

The self-hosting assessment command:

1. Loads your project manifest and structure
2. Generates all 4 meta-models (GenerationPlan, Capability, Extension, Topology)
3. Runs comprehensive validation across all models
4. Reports adoption status: Ready, WarningsPending, or Failed
5. Provides remediation guidance for any issues found

See: SELF_HOSTING_CLI_ASSESSMENT.md for complete guide including:

• Detailed usage examples
• Output format reference
• Integration patterns (CI/CD, dashboards)
• Remediation guide
• Troubleshooting

Manifest-driven generation

Generation now comes from [[generate]] entries in archkit.project.toml.

Example:

[project]
name = "My Project"

[[generate]]
name = "schema"
model = "authored/domain.aks"
target = "json.schema"
output = "generated/domain.schema.json"

[[generate]]
name = "types"
model = "authored/domain.aks"
target = "typescript.type"
output = "generated/domain.types.ts"

[[generate]]
name = "summary"
model = "authored/domain.aks"
target = "json.schema"
output = "generated/domain.summary.md"
template = "artifact.summary.md"

Run configured generation set:

nix develop -c cargo run -p archkit-cli -- project generate --root ./my-project

Current built-in targets:

• json.schema
• typescript.type

Generation inspection flow

Write plan + artifacts + report

nix develop -c cargo run -p archkit-cli -- project generate --root ./my-project

Writes generated outputs plus persisted files:

• reports/generate/project-generate.archkit.plan.json
• reports/generate/project-generate.archkit.report.json

Show persisted plan

nix develop -c cargo run -p archkit-cli -- project generate --root ./my-project --plan

Use when reviewing planned artifact ids, targets, inputs, renderers, and output paths.

Check persisted plan drift

nix develop -c cargo run -p archkit-cli -- project generate --root ./my-project --check

Use when manifest or model changed and you need to know whether persisted plan stale. Check reads current manifest-derived plan and compares it to persisted reports/generate/project-generate.archkit.plan.json.

Explain all planned artifacts

nix develop -c cargo run -p archkit-cli -- project generate --root ./my-project --explain

Use when you need inventory of artifact ids, targets, renderers, templates, inputs, and output paths.

Explain one artifact by id

nix develop -c cargo run -p archkit-cli -- project generate --root ./my-project --explain --artifact-id json.schema:schema

Explain one artifact by output path

nix develop -c cargo run -p archkit-cli -- project generate --root ./my-project --explain --output-path generated/domain.schema.json

Template overrides

Template-backed generation supports:

• explicit template_override = "..."
• conventional project overrides in templates/codegen/
• conventional shared overrides in templates/shared/codegen/
• builtin fallback templates

Resolution order:

explicit override
-> templates/codegen/
-> templates/shared/codegen/
-> builtin template

Unused conventional override files do not fail generation. They emit warning diagnostics in generation report and persisted reports/generate/project-generate.archkit.report.json.

File ownership rules

Practical workflow

1. edit models under authored/
2. adjust [[generate]] manifest entries if outputs change
3. run project generate
4. inspect with --plan, --check, or --explain when needed
5. review generated outputs plus persisted project-generate.archkit.plan.json and project-generate.archkit.report.json
6. run layout-check and dogfood for broader project health

Notes

• output paths for [[generate]] entries must stay under generated/
• generation plan stays deterministic and persisted under reports/generate/
• artifact lookups use either stable artifact_id or relative output_path
• use Nix-wrapped commands in this repo

Future Enhancements (Optional M7 Roadmap)

The generation-spec implementation is complete as of 2026-06-23. Optional enhancements are documented in the M7 enhancement roadmap:

See: docs/plans/archkit-codegen-m7-enhancement-roadmap.md

Planned future work includes:

• Diff/Report Command: Rich visibility into generation plan changes with HTML diffing
• Additional Targets: Python (dataclass/Pydantic), Go, Rust, GraphQL, OpenAPI, Protobuf
• Richer UX: Enhanced explain output, interactive CLI explorer, HTML plan viewer, verbose reporting
• Cross-Cutting: Metrics collection, config profiles, dry-run mode, plugin system

These enhancements are not blockers for the current generation-spec flow and can be implemented in phases.