igniter 0.5.1 → 0.5.2

data/docs/dev/README.md

@@ -0,0 +1,48 @@
+# Igniter Dev
+
+Use this section for public contributor-facing architecture, package boundaries,
+and current design constraints.
+
+Internal cycle history, agent handoffs, research horizon material, external
+expert reports, and legacy deep references live under `playgrounds/docs/` and
+are not part of the public documentation surface.
+
+## Canonical Dev Docs
+
+- [Current Runtime Snapshot](./current-runtime-snapshot.md)
+- [Architecture](./architecture.md)
+- [Execution Model](./execution-model.md)
+- [Contract Persistence Target Plan](./contract-persistence-target-plan.md)
+- [Module System](./module-system.md)
+- [Package Map](./package-map.md)
+- [Data Ownership](./data-ownership.md)
+- [Embed Target Plan](./embed-target-plan.md)
+- [Application Target Plan](./application-target-plan.md)
+- [Application And Web Integration](./application-web-integration.md)
+- [Application Web POC Pattern Guide](./application-web-poc-pattern-guide.md)
+- [AI And Agents Target Plan](./ai-agents-target-plan.md)
+- [Cluster Target Plan](./cluster-target-plan.md)
+- [Igniter Web Target Plan](./igniter-web-target-plan.md)
+- [MCP Adapter Package](./mcp-adapter-package-spec.md)
+- [Document Rotation](./document-rotation.md)
+- [Agent Orchestra DNA](./agent-orchestra-dna.md)
+- [Architect Supervisor Bootstrap](./architect-supervisor-bootstrap.md)
+
+## Package And Layer Boundaries
+
+- [Core](../guide/core.md)
+- [App](../guide/app.md)
+- [Cluster](../guide/cluster.md)
+- [`igniter-extensions`](../../packages/igniter-extensions/README.md)
+
+## Public Docs Rule
+
+- Keep user onboarding in `docs/guide/`.
+- Keep package-local quick reference in `packages/<gem>/README.md`.
+- Keep public architecture and placement decisions in `docs/dev/`.
+- Keep private research, expert analysis, handoff history, and agent working
+  tracks in `playgrounds/docs/`.
+- Prefer updating a package README and guide index before writing new deep
+  public prose.
+- Rotate stale public docs into `playgrounds/docs/` once their accepted content
+  has been compressed into guide, dev, example, or package reference.

data/docs/dev/agent-orchestra-dna.md

@@ -0,0 +1,271 @@
+# Agent Orchestra DNA
+
+Status: portable process seed
+Owner: Architect Supervisor
+Last updated: 2026-05-12
+
+This document describes the minimal repeatable pattern for deploying an
+agent-orchestrated development loop in another project.
+
+It is intentionally project-agnostic. Use it as the DNA for a new workspace,
+then let the local Architect Supervisor adapt names, roles, folders, and cadence
+to the target project.
+
+## Core Thesis
+
+Agents need a map, not the whole history.
+
+The system works when every participant can answer:
+
+- where are we now?
+- what is canonical?
+- what is being worked now?
+- who owns each decision?
+- what evidence proves a change?
+- where should useful pressure route next?
+
+The short formula:
+
+```text
+Role + Context + Card + Lens + Authority + Route
+```
+
+Each part prevents a common failure:
+
+| Part | Prevents |
+| --- | --- |
+| Role | Agent invents its own job or claims another role's authority |
+| Context | Agent rereads history and reconstructs a stale project model |
+| Card | Slice expands beyond the current task |
+| Lens | Review asks the wrong questions |
+| Authority | Discussion or pressure accidentally becomes canon |
+| Route | Useful insight remains prose instead of becoming work |
+
+## Minimal Workspace Shape
+
+Default path for a new project:
+
+```text
+docs/agents/
+  README.md
+  current-status.md
+  operating-model.md
+  roles/
+    README.md
+  handoff/
+    README.md
+    onboarding-card-template.md
+    instance-routing.md
+  tracks/
+    README.md
+  discussions/
+    README.md
+  decisions/
+    README.md
+  lineups/
+    README.md
+  inbox/
+    README.md
+  archive/
+```
+
+If the project already has a documentation convention, adapt the path. The
+important thing is not the folder name. The important thing is that active maps,
+ephemeral tracks, decisions, role profiles, discussions, and archives are not
+mixed together.
+
+## Roles
+
+Start with a small orchestra. Add roles only when the work produces a real
+pressure that a current role cannot hold cleanly.
+
+| Role | Purpose |
+| --- | --- |
+| Architect Supervisor | Owns rounds, scope, authority, gates, and final routing |
+| Implementation Agent | Makes bounded code changes after authority exists |
+| Research Agent | Builds proofs, maps uncertainty, validates hypotheses |
+| Domain Pressure Agent | Pushes from product, user, domain, and business reality |
+| QA/Test Agent | Runs targeted verification and turns failures into evidence |
+| Status Curator | Maintains current maps, round summaries, and next-state clarity |
+| External Pressure Reviewer | Fresh-context critique; pressure only, no canon authority |
+| Archive/Form Expert | Separates history, canon, archive, and zombie documents |
+| Line Up Summarizer | Compresses bulky sources into compact memory cards |
+| History Curator | Long-cycle archaeology, preservation, and context hygiene |
+
+Role and agent are different:
+
+```text
+Agent: [Spark CRM Runtime Reviewer]
+Role:  external-pressure-reviewer
+Lens:  runtime-pressure
+```
+
+One role may have multiple instances. One agent may borrow a lens for a single
+card, but it does not replace the base role.
+
+## Card Codes
+
+Use compact card ids so humans can dispatch parallel work without rereading the
+whole plan.
+
+```text
+Card: S1-R2-C3-P1
+```
+
+Meaning:
+
+| Code | Meaning |
+| --- | --- |
+| `S1` | Stage 1 |
+| `R2` | Supervisor round 2 |
+| `C3` | Card 3 inside the round |
+| `P` | Parallel-safe |
+| `P1`, `P2` | Parallel series; same number may start together |
+| `B` | Blocked or ordered; check dependencies before starting |
+| `S` | Serial or supervisor-only; usually after a round barrier |
+| `A` | Architect/authority decision; no implementation unless scoped |
+| `I` | Implementation/code-writing slice; tests or proofs expected |
+
+Dispatch pattern:
+
+```text
+R = [[C1-P1, C2-P1] -> C3-S -> [C4-P2, C5-P2]]
+```
+
+`C1-P1` and `C2-P1` may run together. `C3-S` runs after P1 closes. `C4-P2` and
+`C5-P2` may run together after the serial barrier.
+
+## Instance Routes
+
+Every agent instance should choose a startup route before work.
+
+| Situation | Route | Use when |
+| --- | --- | --- |
+| New chat / fresh agent | `INIT` | No previous handoff in this chat |
+| Same agent, new card | `UPDATE` | Role is known, work changed |
+| Same card in progress | `IN_FLIGHT_REFRESH` | Need to re-check changed files or maps |
+| Returning after delay | `STALE_REFRESH` | Stage, round, gate, or same-role work moved |
+| Discussion mode | `DISCUSSION` | Producing critique or pressure, not code/canon |
+| Stage-level role | `STAGE_LOOP` | Long-cycle work without per-round cards |
+
+Minimal startup statement:
+
+```text
+Route:
+Agent:
+Role:
+Card:
+Current stage/round observed:
+Neighbor risk:
+```
+
+## Authority Boundary
+
+Output types are not equal.
+
+| Output type | Authority |
+| --- | --- |
+| Inbox note | Unrouted input |
+| Discussion | Pressure only |
+| Review | Signal that needs intake |
+| Track | Evidence for one bounded slice |
+| Proposal | Candidate design or semantics |
+| Spec | Canon after acceptance/sync |
+| Decision | Architect-owned authorization |
+| Implementation | Code inside an authorized surface |
+
+The word `proceed` in a review means "safe to route onward", not "authorized to
+implement".
+
+## Round Loop
+
+The default loop:
+
+```text
+Architect Supervisor
+  -> opens cards and authority boundaries
+Agents
+  -> execute bounded slices and handoff
+External Pressure / QA
+  -> challenge and verify
+Status Curator / Meta
+  -> updates maps and extracts next blockers
+Architect Supervisor
+  -> closes, redirects, authorizes, or opens next round
+```
+
+Keep the loop small enough that the current state can be reloaded from the maps,
+not reconstructed from the archive.
+
+## Document Lifecycle
+
+No document should have an undefined status.
+
+```text
+inbox
+  -> reject
+  -> discussion
+  -> track
+  -> decision
+  -> proposal
+  -> spec
+  -> lineup
+  -> archive
+```
+
+Use lineups for context hoisting:
+
+```text
+large source document
+  -> compact Line Up summary
+  -> source remains authoritative for exact proof logs
+  -> active maps link to Line Up, not bulky history
+```
+
+Use archive mode for history:
+
+```text
+history is preserved
+  but not required reading for new work
+```
+
+## Safety Rules
+
+- Do not read the entire repository unless explicitly assigned archaeology.
+- Do not revert, stage, clean, or remove files that may belong to another agent.
+- Do not promote pressure, discussion, or research into canon without routing.
+- Do not implement behavior before authority exists.
+- Do not hide unresolved blockers behind a positive summary.
+- Prefer exact file links and compact handoffs over narrative memory.
+- Treat multiple instances of the same role as normal.
+
+## Stage 0 Bootstrap
+
+For a new project, the first stage should produce only a map and operating
+surface. Avoid code changes unless the user explicitly asks.
+
+Suggested first round:
+
+```text
+S0-R1-C1-A  Architect Supervisor: create project intake map
+S0-R1-C2-P1 Research Agent: project structure and build/test map
+S0-R1-C3-P1 Domain Pressure Agent: product/domain pain map
+S0-R1-C4-P1 Archive/Form Expert: documentation/context map
+S0-R1-X1-S  External Pressure Reviewer: fresh-context critique
+S0-R1-C5-S  Status Curator: current-status and next round
+```
+
+After Stage 0, the project should have:
+
+- a current status map;
+- a role map;
+- a first backlog of concrete tracks;
+- a clear list of protected surfaces;
+- known build/test commands;
+- known document rotation rules.
+
+## Copy-Paste Bootstrap
+
+Use [Architect Supervisor Bootstrap](./architect-supervisor-bootstrap.md) to
+initialize a new project chat.
+

data/docs/dev/ai-agents-target-plan.md

@@ -0,0 +1,178 @@
+# AI And Agents Target Plan
+
+This track moves live AI and agent behavior out of application examples and
+back into package-owned Igniter surfaces.
+
+Status: accepted direction, not stable API.
+
+## Motivation
+
+Applications should configure AI and agents; they should not invent provider
+clients, agent loops, tool policy, memory, or replay seams locally.
+
+The Companion application is the current proof pressure: it needs live LLM
+value, credentials, stored user state, and future assistant capsules, but those
+capabilities must become reusable package primitives before they harden inside
+one app.
+
+## Package Ownership
+
+### `igniter-ai`
+
+Owns provider-neutral AI execution:
+
+- provider clients and model request/response envelopes
+- credentials-aware client configuration
+- live, fake, and recorded execution modes
+- prompt/message/transcript value objects
+- usage, errors, provider metadata, and response normalization
+- evaluation and replay seams for examples and tests
+
+Does not own:
+
+- long-running agent loops
+- application routing or boot lifecycle
+- web rendering
+- MCP transport
+
+First provider target: OpenAI Responses API, wrapped behind an Igniter request
+envelope so examples do not call provider-specific clients directly.
+
+### `igniter-agents`
+
+Owns agent runtime semantics over contracts and AI:
+
+- agent definitions, runs, turns, traces, and lifecycle state
+- tool catalogs, tool calls, and tool policy
+- memory/context interfaces
+- planning and handoff envelopes
+- human gates, approvals, and resumable waits
+- supervisor and worker coordination vocabulary
+
+Does not own:
+
+- provider-specific HTTP clients
+- Rails/Rack/web rendering
+- distributed mesh placement
+- application-specific assistant features
+
+`igniter-agents` depends conceptually on `igniter-ai` for model execution and
+on contracts for typed tools/results. It should stay usable without web.
+
+## Boundary Rules
+
+- `igniter-application` wires credentials, store choices, boot lifecycle, and
+  app-local configuration into AI/agent packages.
+- `igniter-web` renders chat, approval, stream, and review surfaces from
+  application snapshots; it does not run agent logic.
+- `igniter-mcp-adapter` exposes existing tool catalogs over transport; it does
+  not become the agent runtime.
+- `igniter-extensions` may provide tool packs and diagnostics over contracts,
+  but not provider-specific AI execution.
+- Example apps may demonstrate capabilities, but app-local AI code is treated
+  as temporary until the corresponding package primitive exists.
+
+## Human DSL Shape
+
+The package APIs should support two equal forms:
+
+- agent-facing explicit objects for tests, tooling, replay, and generated code
+- human-facing sugar DSL for compact application configuration
+
+Target application shape:
+
+```ruby
+Igniter::Application.define(:companion) do
+  credential :openai_api_key, env: "OPENAI_API_KEY"
+
+  ai do
+    provider :openai, credential: :openai_api_key, model: "gpt-5.2"
+    mode ENV["COMPANION_LIVE"] == "1" ? :live : :fake
+  end
+
+  agents do
+    assistant :daily_companion do
+      use_model :openai
+      use_tools :reminders, :trackers, :countdowns
+      memory :sqlite, namespace: :companion
+      human_gate :approval, for: :destructive_actions
+    end
+  end
+end
+```
+
+This is illustrative, not accepted API.
+
+## First Implementation Slice
+
+Status: package skeleton, application-level AI provider DSL, and minimal
+single-turn agent runtime landed.
+
+1. Create `packages/igniter-ai` with zero production dependencies.
+2. Move the Companion OpenAI Responses behavior behind
+   `Igniter::AI::Providers::OpenAIResponses`.
+3. Add fake and recorded providers so examples stay offline by default.
+4. Add request/response envelopes with normalized `text`, `usage`, `metadata`,
+   and `error`.
+5. Let `igniter-application` configure AI providers through credentials without
+   provider-specific code in the app.
+6. Keep Companion as the reference consumer and remove its local provider once
+   the package slice is green.
+
+Acceptance:
+
+- no network calls in default specs or example smoke
+- live mode requires explicit environment opt-in
+- provider errors return structured failure envelopes
+- credentials remain redacted in profiles and manifests
+- Companion still runs in fake/offline mode and can opt into live mode
+
+## Second Implementation Slice
+
+Status: minimal package skeleton and application-level agent DSL landed;
+capsule transfer can now carry declared agents as capabilities; memory,
+handoff, human gates, and contracts-first tool execution are still next.
+
+1. Create `packages/igniter-agents` around minimal agent run state.
+2. Treat tools as contracts-first callables.
+3. Add a single-turn assistant runner over `igniter-ai`.
+4. Add trace envelopes that can be rendered by application/web surfaces.
+5. Add human gate state without requiring a web package.
+
+Acceptance:
+
+- agent runs are serializable and replayable
+- tool calls expose typed inputs/results
+- web can render run state without owning runtime logic
+- applications can run a simple assistant without custom loop code
+
+## Agent-Aware Capsule Transfer
+
+Status: first deterministic slice landed.
+
+Capsule transfer treats agents as declared application capabilities. Transfer
+reports carry agent declarations through capsule reports, handoff manifests,
+inventories, intake/apply plans, and receipts. Readiness can block an agent
+capsule when the required AI provider is not declared.
+
+Transfer does not run agents by default. Agents may review reports later, but
+the source of truth remains the deterministic transfer pipeline.
+
+## Legacy Filter
+
+Legacy package layout is useful as vocabulary, not as code to restore blindly.
+
+Accepted concepts:
+
+- separate AI and agent packages
+- provider abstraction
+- tool registry
+- skill/runtime-contract idea
+- registry-backed agent adapter
+
+Rejected for now:
+
+- broad SDK umbrella
+- server-first agent sessions
+- package surfaces that require distributed runtime
+- provider APIs leaking into application examples

data/docs/dev/application-target-plan.md

@@ -0,0 +1,45 @@
+# Application Target Plan
+
+`Application` is the contracts-native local host/profile layer above `Embed`.
+It assembles contracts, packs, services, loaders, schedulers, host adapters, and
+diagnostics into one local runtime profile.
+
+## Owns
+
+- `Kernel`, `Profile`, and `Environment`
+- app config, manifest, layout, and blueprint
+- providers, services, contracts, and local interfaces
+- host, loader, scheduler, boot, shutdown, and lifecycle reports
+- app-local session durability and transport-ready local invoker seams
+- application capsules, sparse structure plans, imports, exports, handoff,
+  transfer, and activation review artifacts
+
+## Does Not Own
+
+- embedded graph semantics
+- distributed routing, placement, ownership, membership, or failover
+- generic web rendering or route activation
+- old `Igniter::App` subclass/global mutation semantics
+- scaffold behavior inside the minimal runtime
+
+## Boundary Rules
+
+- `Embed` defines executable work.
+- `Application` hosts local app runtime and app-owned lifecycle.
+- `Stack` coordinates multiple apps only when needed.
+- `Cluster` adds distributed execution above local runtime.
+- `igniter-web` owns screens, components, routes, and rendering.
+
+## Current Shape
+
+The clean-slate package lives in `packages/igniter-application` and already
+contains the new kernel/profile/environment direction, explicit lifecycle
+plans, provider reports, app manifests, sparse layouts, capsules, transfer
+review, host activation review, and receipt-shaped evidence artifacts.
+
+## Success
+
+Application is successful when one local app can boot without legacy/core
+assumptions, profiles are explicit and comparable, host seams are adapters, and
+old `Igniter::App` can be deleted as architecture rather than preserved as a
+compatibility burden.

data/docs/dev/application-web-integration.md

@@ -0,0 +1,59 @@
+# Application And Web Integration
+
+This note defines the public integration boundary between
+`igniter-application` and `igniter-web`.
+
+## Boundary
+
+`igniter-application` owns:
+
+- application identity and environment finalization
+- local services, providers, contracts, and runtime state
+- app-owned snapshots and evidence artifacts
+- mutation policy and lifecycle decisions
+
+`igniter-web` owns:
+
+- mounted web surfaces
+- request/response handling for the mounted review surface
+- `MountContext` and read-oriented service access
+- app-local feedback rendering, forms, and screen structure
+- web surface manifests and metadata exported into capsule/review artifacts
+
+Neither package should make the other a hidden dependency. Applications can
+exist without web surfaces, and web surfaces should mount over an explicit
+finalized environment instead of discovering application internals.
+
+## Integration Shape
+
+The accepted shape is:
+
+1. Application builds a finalized environment.
+2. Web mount binds to that environment.
+3. Web renders from an explicit app-owned snapshot.
+4. Commands route back through app-owned services.
+5. `/events` and `/report` or `/receipt` expose the same detached state used by
+   the web surface.
+
+This pattern is proven by the showcase apps and described for users in:
+
+- [Application Showcase Portfolio](../guide/application-showcase-portfolio.md)
+- [Interactive App Structure](../guide/interactive-app-structure.md)
+- [Application Showcase Portfolio](../guide/application-showcase-portfolio.md)
+
+## Non-Goals
+
+The integration boundary does not imply:
+
+- production server behavior
+- auth, persistence, scheduler, connectors, or live transport
+- browser automation by default
+- a marker DSL, route DSL, or generic UI component API
+- application-owned inspection of web page classes
+- web-owned mutation of application state outside explicit command handlers
+
+## Extraction Rule
+
+Repeated shapes should stay app-local until at least two showcase apps prove the
+same abstraction with low ceremony. Promote only the pieces that reduce real
+duplication without hiding ownership.