@citadel-labs/citadel 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export * from './types/index.js';
+export * from './core/append-bead.js';
+export * from './core/grand-archives.js';
+export * from './core/process-registry.js';
+export * from './core/nudge.js';
+export * from './core/command-bead.js';
+export * from './core/worktree-manager.js';
+export * from './core/courier.js';
+export * from './core/pre-spawn-check.js';
+export * from './core/spawn-citizen.js';
+export * from './core/timeout-watchdog.js';
+export * from './core/validate-tribute.js';
+export * from './core/citizen-bootstrap.js';
+export * from './core/fo-state.js';
+export * from './core/citizen-tribute.js';
+export * from './core/fo-nudge-watcher.js';
+export * from './core/fo-nudge-wiring.js';
+export * from './core/fo-handlers/ceiling-hit.js';
+export * from './core/fo-handlers/slot-open.js';
+export * from './core/fo-dispatch.js';
+export * from './core/fo-command-processor.js';
+export * from './core/fo-retry-policy.js';
+export * from './core/fo-escalation.js';
+export * from './core/outpost-registry.js';
+export * from './core/blocked-outposts.js';
+export * from './core/fo-broadcast.js';
+export * from './core/fo-relay.js';
+export * from './core/fo-task-report.js';
+export * from './core/fo-webhook.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+export * from './types/index.js';
+export * from './core/append-bead.js';
+export * from './core/grand-archives.js';
+export * from './core/process-registry.js';
+export * from './core/nudge.js';
+export * from './core/command-bead.js';
+export * from './core/worktree-manager.js';
+export * from './core/courier.js';
+export * from './core/pre-spawn-check.js';
+export * from './core/spawn-citizen.js';
+export * from './core/timeout-watchdog.js';
+export * from './core/validate-tribute.js';
+export * from './core/citizen-bootstrap.js';
+export * from './core/fo-state.js';
+export * from './core/citizen-tribute.js';
+export * from './core/fo-nudge-watcher.js';
+export * from './core/fo-nudge-wiring.js';
+export * from './core/fo-handlers/ceiling-hit.js';
+export * from './core/fo-handlers/slot-open.js';
+export * from './core/fo-dispatch.js';
+export * from './core/fo-command-processor.js';
+export * from './core/fo-retry-policy.js';
+export * from './core/fo-escalation.js';
+export * from './core/outpost-registry.js';
+export * from './core/blocked-outposts.js';
+export * from './core/fo-broadcast.js';
+export * from './core/fo-relay.js';
+export * from './core/fo-task-report.js';
+export * from './core/fo-webhook.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC"}

package/dist/types/agent.d.ts

@@ -0,0 +1,47 @@
+import type { ChildProcess } from 'node:child_process';
+/**
+ * Environment variables injected into every Citizen process.
+ */
+export interface CitizenEnv {
+    CITADEL_OUTPOST: string;
+    CITADEL_ARCHETYPE: string;
+    CITADEL_CITIZEN_ID: string;
+    CITADEL_TASK_ID: string;
+    CITADEL_WORKTREE: string;
+    CITADEL_BEADS_ROOT: string;
+}
+/**
+ * Options for spawning an agent process.
+ */
+export interface AgentSpawnOptions {
+    systemPromptPath: string;
+    toolsetManifestPath: string;
+    workingDirectory: string;
+    env: CitizenEnv & Record<string, string>;
+}
+/**
+ * Result from a completed agent process.
+ */
+export interface AgentExitResult {
+    exitCode: number | null;
+    signal: string | null;
+}
+/**
+ * Agent runtime abstraction. Each supported agent runtime implements this.
+ */
+export interface AgentRuntime {
+    /** Identifier for this runtime (e.g. 'claude-code', 'cursor', 'copilot') */
+    readonly name: string;
+    /** Binary or command used to launch the agent */
+    readonly bin: string;
+    /**
+     * Spawn an agent process. Returns the child process handle.
+     * The caller (Courier) manages lifecycle via the returned ChildProcess.
+     */
+    spawn(options: AgentSpawnOptions): ChildProcess;
+    /**
+     * Build CLI arguments for the agent from spawn options.
+     */
+    buildArgs(options: AgentSpawnOptions): string[];
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/types/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,iBAAiB,GAAG,YAAY,CAAC;IAEhD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,EAAE,CAAC;CACjD"}

package/dist/types/agent.js

@@ -0,0 +1,4 @@
+// Agent runtime abstraction — agent-agnostic interface
+// Supports: Claude Code, Cursor, Copilot, or any compatible CLI agent
+export {};
+//# sourceMappingURL=agent.js.map

package/dist/types/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,sEAAsE"}

package/dist/types/beads.d.ts

@@ -0,0 +1,175 @@
+export declare const SCHEMA_VERSION = "9.0";
+export type BeadType = 'MAIL' | 'TRIBUTE' | 'IDENTITY' | 'COMMAND' | 'NUDGE';
+export interface BaseBead {
+    bead_id: string;
+    bead_type: BeadType;
+    schema_version: string;
+    created_at: string;
+    metadata?: Record<string, unknown>;
+}
+export type MailType = 'TASK_ASSIGNMENT' | 'DEPENDENCY_RESOLVED' | 'OPERATOR_NOTE' | 'PEER_RELAY' | 'TRIBUTE_INVALID' | 'TASK_REPORT' | 'RELAY_REQUEST';
+export type MailDirection = 'downward' | 'upward';
+export interface SpawnHint {
+    archetype: string;
+    citizen_id: string;
+}
+export interface MailBead extends BaseBead {
+    bead_type: 'MAIL';
+    task_id?: string;
+    mail_type: MailType;
+    from: string;
+    to: string;
+    subject: string;
+    read: boolean;
+    retry_of: string | null;
+    spawn_hint?: SpawnHint;
+    payload: MailPayload;
+}
+export type MailPayload = TaskAssignmentPayload | DependencyResolvedPayload | OperatorNotePayload | PeerRelayPayload | TributeInvalidPayload | TaskReportPayload | RelayRequestPayload;
+export interface TaskAssignmentPayload {
+    archetype: string;
+    citizen_id: string;
+    priority: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+    title: string;
+    description: string;
+    acceptance_criteria: string[];
+    context_refs: string[];
+    dependencies: string[];
+    timeout_seconds: number;
+}
+export interface DependencyResolvedPayload {
+    resolved_task_id: string;
+    resolved_by_outpost: string;
+    tribute_ref: string;
+    pr_url?: string;
+    summary: string;
+}
+export interface OperatorNotePayload {
+    body: string;
+    task_id?: string;
+}
+export interface PeerRelayPayload {
+    origin_outpost: string;
+    origin_mail_ref: string;
+    subject: string;
+    body: string;
+    context_refs: string[];
+}
+export interface TributeInvalidPayload {
+    tribute_ref: string;
+    errors: string[];
+    suggested_action: 'RETRY' | 'ESCALATE';
+}
+export type TaskReportStatus = 'IN_PROGRESS' | 'BLOCKED' | 'NEEDS_INPUT' | 'COMPLETE';
+export interface TaskReportPayload {
+    status: TaskReportStatus;
+    summary: string;
+    blockers: string[];
+    questions: string[];
+    context_refs: string[];
+}
+export interface RelayRequestPayload {
+    intended_for: string;
+    subject: string;
+    body: string;
+    context_refs: string[];
+}
+export type TributeStatus = 'SUCCESS' | 'PARTIAL' | 'FAILED';
+export interface TributeBead extends BaseBead {
+    bead_type: 'TRIBUTE';
+    citizen_id: string;
+    task_id: string;
+    originating_mail_ref: string;
+    archetype: string;
+    outpost: string;
+    worktree: string;
+    attempt: number;
+    status: TributeStatus;
+    pr_url?: string;
+    summary: string;
+    artifacts: string[];
+    acceptance_met: boolean[];
+    elapsed_seconds: number;
+}
+export interface IdentityBead extends BaseBead {
+    bead_type: 'IDENTITY';
+    role: 'first-officer';
+    display_name: string;
+    agent: string;
+    citadel_root: string;
+    last_session_at: string;
+}
+export type CommandName = 'dispatch' | 'note' | 'retry' | 'resolve';
+export interface CommandBead extends BaseBead {
+    bead_type: 'COMMAND';
+    command: CommandName;
+    args: CommandArgs;
+    processed: boolean;
+}
+export type CommandArgs = DispatchArgs | NoteArgs | RetryArgs | ResolveArgs;
+export interface DispatchArgs {
+    outpost: string;
+    task: string;
+    archetype?: string;
+}
+export interface NoteArgs {
+    outpost: string;
+    body: string;
+    task_id?: string;
+}
+export interface RetryArgs {
+    task_id: string;
+}
+export type ResolveAction = 'retry' | 'abandon' | 'rewrite';
+export interface ResolveArgs {
+    task_id: string;
+    action: ResolveAction;
+    note?: string;
+}
+export type NudgeSignalType = 'TRIBUTE_WRITTEN' | 'MAIL_RECEIVED' | 'COMMAND_RECEIVED' | 'NO_TASK_ASSIGNMENT' | 'CITIZEN_EXIT_ERROR' | 'CITIZEN_TIMEOUT' | 'PARALLELISM_CEILING_HIT';
+export interface NudgeBead extends BaseBead {
+    bead_type: 'NUDGE';
+    signal_type: NudgeSignalType;
+    payload: NudgePayload;
+    processed: boolean;
+}
+export type NudgePayload = TributeWrittenPayload | MailReceivedPayload | CommandReceivedPayload | NoTaskAssignmentPayload | CitizenExitErrorPayload | CitizenTimeoutPayload | ParallelismCeilingHitPayload;
+export interface TributeWrittenPayload {
+    outpost: string;
+    tribute_bead_id: string;
+    task_id: string;
+    worktree: string;
+}
+export interface MailReceivedPayload {
+    mail_bead_id: string;
+    mail_type: MailType;
+    from: string;
+}
+export interface CommandReceivedPayload {
+    command_bead_id: string;
+    command: CommandName;
+}
+export interface NoTaskAssignmentPayload {
+    outpost: string;
+    triggering_mail_bead_id: string;
+}
+export interface CitizenExitErrorPayload {
+    outpost: string;
+    citizen_id: string;
+    task_id: string;
+    exit_code: number | null;
+    worktree: string;
+}
+export interface CitizenTimeoutPayload {
+    outpost: string;
+    citizen_id: string;
+    task_id: string;
+    spawned_at: string;
+    worktree: string;
+}
+export interface ParallelismCeilingHitPayload {
+    outpost: string;
+    active_count: number;
+    ceiling: number;
+}
+//# sourceMappingURL=beads.d.ts.map

package/dist/types/beads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beads.d.ts","sourceRoot":"","sources":["../../src/types/beads.ts"],"names":[],"mappings":"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"}

package/dist/types/beads.js

@@ -0,0 +1,4 @@
+// Citadel Bead Schema — v9.0
+// All Beads are append-only JSONL records, written via appendBead().
+export const SCHEMA_VERSION = '9.0';
+//# sourceMappingURL=beads.js.map

package/dist/types/beads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beads.js","sourceRoot":"","sources":["../../src/types/beads.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,qEAAqE;AAErE,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './beads.js';
+export * from './registry.js';
+export * from './agent.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,4 @@
+export * from './beads.js';
+export * from './registry.js';
+export * from './agent.js';
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/types/registry.d.ts

@@ -0,0 +1,110 @@
+export type OutpostStatus = 'ACTIVE' | 'INACTIVE' | 'SUSPENDED';
+export interface OutpostRegistryEntry {
+    slug: string;
+    path: string;
+    status: OutpostStatus;
+    registered_at: string;
+    default_archetype?: string;
+    max_citizens?: number;
+}
+export interface OutpostRegistry {
+    schema_version: string;
+    outposts: OutpostRegistryEntry[];
+}
+export interface ProcessRegistryEntry {
+    pid: number;
+    spawned_at: string;
+    worktree_path: string;
+    task_id: string;
+}
+export interface WorktreeEntry {
+    path: string;
+    branch: string;
+    head: string;
+    prunable: boolean;
+}
+export type ArchetypeStatus = 'active' | 'planned';
+export interface ArchetypeRegistryEntry {
+    key: string;
+    description: string;
+    status: ArchetypeStatus;
+}
+export interface ArchetypeRegistry {
+    schema_version: string;
+    archetypes: ArchetypeRegistryEntry[];
+}
+export interface ArchetypeSystemPrompt {
+    preamble_ref: string;
+    body_ref: string;
+}
+export interface ArchetypeToolset {
+    base_ref: string;
+    override_ref: string;
+}
+export interface ArchetypeConfig {
+    key: string;
+    schema_version: string;
+    display_name: string;
+    system_prompt: ArchetypeSystemPrompt;
+    toolset: ArchetypeToolset;
+    constraints: {
+        max_tokens_per_turn: number;
+        temperature: number;
+        model: string;
+    };
+}
+export interface FirstOfficerConfig {
+    schema_version: string;
+    display_name: string;
+    singleton: boolean;
+    assignable: boolean;
+    agent: string;
+    system_prompt_ref: string;
+    toolset_ref: string;
+    model: string;
+    constraints: {
+        temperature: number;
+        max_tokens_per_turn: number;
+    };
+    retry_policy: RetryPolicy;
+    nudge_retention: number;
+}
+export interface RetryPolicy {
+    max_retries: number;
+    retry_on: string[];
+    partial_strategy: string;
+    on_ceiling_reached: string;
+}
+export interface CourierConfig {
+    citadel_root: string;
+    poll_interval_ms: number;
+    debounce_ms: number;
+    default_max_citizens: number;
+    citizen_timeout_seconds: number;
+    log_level: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+    log_path: string;
+}
+export interface ToolEntry {
+    name: string;
+    enabled: boolean;
+    allowed_commands?: string[];
+}
+export interface Toolset {
+    schema_version: string;
+    description: string;
+    tools: ToolEntry[];
+}
+export interface ResolvedArchetype {
+    key: string;
+    display_name: string;
+    preamble_path: string;
+    system_prompt_path: string;
+    toolset_manifest_path: string;
+    model: string;
+    agent_binary: string;
+    constraints: {
+        max_tokens_per_turn: number;
+        temperature: number;
+    };
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/types/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/types/registry.ts"],"names":[],"mappings":"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"}

package/dist/types/registry.js

@@ -0,0 +1,3 @@
+// Outpost Registry and Grand Archives types
+export {};
+//# sourceMappingURL=registry.js.map

package/dist/types/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/types/registry.ts"],"names":[],"mappings":"AAAA,4CAA4C"}

package/docs/README.md

@@ -0,0 +1,7 @@
+# Citadel Documentation
+
+- [Getting Started](./getting-started.md) - Install, initialize, and dispatch your first task
+- [Architecture](./architecture.md) - System design, bead types, chain of command
+- [CLI Reference](./cli-reference.md) - All commands, flags, and examples
+- [Configuration](./configuration.md) - courier.config.yaml, outpost overrides, archetype setup
+- [Contributing](./contributing.md) - Development setup, testing, and PR guidelines

package/docs/architecture.md

@@ -0,0 +1,106 @@
+# Architecture
+
+## Chain of Command
+
+```
+Commander (you)
+    |  issues orders via CLI
+    v
+First Officer (persistent LLM agent, agent-agnostic)
+    |  selects archetype, mints citizen_id, writes Mail
+    v
+Courier (daemon)
+    |  watches filesystem, manages worktrees, spawns Citizens
+    v
+Citizens (cold-start LLM agents in isolated git worktrees)
+    |  read Mail, do work, write Tribute
+    v
+First Officer receives Tribute, validates, broadcasts, retries or escalates
+```
+
+| Role | What It Does | Writes |
+|---|---|---|
+| **Commander** | Issues orders, reviews Broadcasts | Command Beads |
+| **First Officer** | Orchestrates everything — dispatch, retry, escalate | Mail Beads (downward) |
+| **Courier** | Watches filesystem, spawns Citizens, manages worktrees | Nudge Beads only |
+| **Citizens** | Execute tasks in isolated worktrees | Tribute + Mail (upward) |
+
+## Bead Types
+
+All state lives in append-only JSONL files, written through `appendBead()` with lockfile serialization.
+
+| Bead | Purpose | Path |
+|---|---|---|
+| **Mail** | Universal message envelope, sole wake trigger | `.beads/mail/*.jsonl` |
+| **Tribute** | Work output — status, artifacts, acceptance criteria | `.beads/tribute/*.jsonl` |
+| **Identity** | First Officer persistent identity | `.citadel/identity.jsonl` |
+| **Command** | Commander input (dispatch, note, retry, resolve) | `.citadel/commands/*.jsonl` |
+| **Nudge** | Courier-to-FO signals (never load-bearing) | `.citadel/nudges.jsonl` |
+
+## Nudge Signal Types
+
+The Courier sends 7 signal types to the First Officer via nudges:
+
+| Signal | Trigger | FO Action |
+|---|---|---|
+| `TRIBUTE_WRITTEN` | Citizen writes tribute | Validate, retry/broadcast/escalate |
+| `MAIL_RECEIVED` | Upward mail from citizen | Route RELAY_REQUEST/TASK_REPORT |
+| `COMMAND_RECEIVED` | Commander writes command | Process dispatch/note/retry/resolve |
+| `CITIZEN_EXIT_ERROR` | Citizen process crashes | Log, consider retry |
+| `CITIZEN_TIMEOUT` | Citizen exceeds timeout | Kill process, nudge FO |
+| `PARALLELISM_CEILING_HIT` | Outpost at max citizens | Log contention, queue work |
+| `NO_TASK_ASSIGNMENT` | No unread mail for citizen | Log, no action needed |
+
+## Parallelism
+
+Multiple Citizens can work the same Outpost simultaneously:
+
+```
+outpost-api-gateway/
+  .beads/                    <-- shared across all Citizens
+    mail/                    <-- inbox = pending work queue
+    tribute/                 <-- all attempts, all tasks
+  worktrees/citizen/
+    task_a1b2c3/             <-- Citizen A workspace
+    task_d4e5f6/             <-- Citizen B workspace
+```
+
+Parallelism ceiling is `max_citizens` per outpost (default 3). When at capacity, tasks queue in the inbox and auto-dispatch when a slot opens.
+
+## Retry Policy
+
+Failed or partial Tribute triggers automatic retry up to `max_retries`. The worktree is preserved — retry Citizens inherit prior state. At the ceiling, the FO escalates to Commander.
+
+## Dependency Resolution
+
+Tasks can declare dependencies. On SUCCESS tribute, the FO scans all outposts for blocked tasks and sends `DEPENDENCY_RESOLVED` mail.
+
+## Inter-Outpost Relay
+
+Citizens can request peer communication via `RELAY_REQUEST` mail. The FO routes it as `PEER_RELAY` to the target outpost.
+
+## Task Reports
+
+Citizens send `TASK_REPORT` mail for status updates:
+
+| Status | FO Action |
+|---|---|
+| `IN_PROGRESS` | Log update |
+| `BLOCKED` | Escalate to Commander |
+| `NEEDS_INPUT` | Escalate to Commander |
+| `COMPLETE` | Log note, await Tribute |
+
+## Lockfile Contract
+
+All bead writes go through `appendBead()`:
+
+1. Lockfile acquisition via `proper-lockfile` (retries: 3, stale: 5s)
+2. Atomic append — single JSON line per write
+3. Best-effort git commit after write
+4. Cross-platform (Windows, macOS, Linux)
+
+Concurrent writes to the same file are serialized. Writes to different files run in parallel.
+
+## State Reconstruction
+
+Full FO state is reconstructed from Mail + Tribute only. Nudge history is disposable. Identity persists; sessions are cattle.

package/docs/cli-reference.md

@@ -0,0 +1,81 @@
+# CLI Reference
+
+## Workspace
+
+| Command | Description |
+|---|---|
+| `citadel init [dir]` | Scaffold `.citadel/`, `grand-archives/`, `outposts/`, `courier.config.yaml` |
+| `citadel status` | Session info, per-outpost overview, pending counts |
+| `citadel reset` | Clear unprocessed commands and nudges |
+| `citadel reset --hard` | Wipe `.citadel/` and citadel-level `.beads/` (outpost beads untouched) |
+
+## Session
+
+| Command | Description |
+|---|---|
+| `citadel start [--agent <runtime>]` | Boot the First Officer (claude-code, cursor, copilot) |
+| `citadel stop` | Graceful shutdown — clears unprocessed nudges, writes session.log |
+| `citadel attach` | Tail session log (Unix: live `tail -f`; Windows: last 20 lines) |
+| `citadel detach` | Disconnect Commander view; session continues |
+
+## Outposts
+
+| Command | Description |
+|---|---|
+| `citadel outpost register --slug <name> --path <path>` | Register a repo as an outpost |
+| `citadel worktree list --outpost <slug>` | Show active worktrees |
+| `citadel worktree prune [--outpost <slug>]` | Clean up orphaned worktrees |
+
+## Commands (Full Form)
+
+| Command | Description |
+|---|---|
+| `citadel command dispatch --outpost <slug> --task <text> [--archetype <key>]` | Assign a task |
+| `citadel command note --outpost <slug> --body <text> [--task-id <id>]` | Send guidance |
+| `citadel command retry --task-id <id>` | Force retry |
+| `citadel command resolve --task-id <id> --action <retry\|abandon\|rewrite> [--note <text>]` | Resolve escalation |
+
+## Top-Level Aliases
+
+| Command | Equivalent |
+|---|---|
+| `citadel dispatch --outpost <slug> --task <text> [--archetype <key>]` | `citadel command dispatch` |
+| `citadel note --outpost <slug> --body <text> [--task-id <id>]` | `citadel command note` |
+| `citadel resolve --task-id <id> --action <action> [--note <text>]` | `citadel command resolve` |
+
+## Inspection
+
+| Command | Description |
+|---|---|
+| `citadel tribute --task <id>` | List all tribute attempts for a task |
+| `citadel trace --task <id>` | Full event timeline (commands, mail, tribute, nudges) |
+
+## Examples
+
+```bash
+# Initialize and start
+citadel init my-project && cd my-project
+citadel outpost register --slug api --path ../api-server
+citadel start
+
+# Dispatch tasks
+citadel dispatch --outpost api --task "Add health check endpoint"
+citadel dispatch --outpost api --task "Write integration tests" --archetype qa-engineer
+
+# Monitor
+citadel status
+citadel attach
+
+# Inspect results
+citadel tribute --task task-abc123
+citadel trace --task task-abc123
+
+# Handle escalations
+citadel resolve --task-id task-abc123 --action retry --note "Try a different approach"
+citadel resolve --task-id task-abc123 --action abandon
+
+# Cleanup
+citadel stop
+citadel worktree prune --outpost api
+citadel reset
+```