Dot documentation

@arki/dot composes an app from typed plugins. These pages are small and organised by job. Pick the one that matches what you are about to do.

 new here?   principles → quickstart → di → plugin-authoring
 shipping?   operations → recipes/deploy → recipes/upgrade
 an agent?   ../llms.txt → agent-guide

Read first

• Principles: the five rules every API, error message and PR is measured against.
• Composition doctrine: declaration-first rules for structuring an app and its features.

For app authors

• Quickstart: build an app, break it on purpose, read the error, inspect it with dot explain and dot doctor.
• Dependency injection: needs, provides, handles, tokens, rename, lazy services and defineFeature.
• A complex setup: a many-plugin app and the order it boots in.
• Plugin authoring: write your own plugin.
• Lifecycle: the five hooks, failure order, idempotency.
• Testing plugins: testPlugin against fakes, testApp across real plugins.
• Logging, shutdown and timeouts: log(), hookSignals, createAppRuntime, hookTimeoutMs.
• Diagnostics: app.manifest, app.diagnostics and the JSON they print.
• Observability: OpenTelemetry traces and metrics, the arki:dot:lifecycle logger.
• The dot command: dot new, dot explain, dot doctor, dot dev.

Recipes

Each recipe ends in one command and its expected output.

• Deploy an app: build the container, run it, check /api/health.
• Upgrade Dot: bump, typecheck, boot-check.

For package authors

• Adapter authoring: expose your package as a Dot plugin through a ./dot subpath export.

For agents

• llms.txt: the map. Read it first.
• Agent guide: inspect, change and verify a Dot app without reading the source.
• AGENTS.md: the laws for changing this package.

For maintainers

• Release policy: SemVer, deprecation, stability.
• Upgrade guide: before and after code for each breaking change.

Worked example

• examples/quickstart.ts: the quickstart app. src/tests/quickstart-example.test.ts boots it, and the quickstart runs dot explain and dot doctor on it.

• Action boundaries: shared contracts, native adapters and authority.

• Upgrade action boundaries: typed failures and validation ownership.