igniter 0.5.1 → 0.5.2

data/docs/dev/package-map.md

@@ -0,0 +1,112 @@
+# Package Map
+
+This is the target ownership map for the new runtime family.
+
+## Root
+
+Root should stay thin:
+
+- umbrella gem wiring
+- load-path/package registration
+- top-level onboarding docs
+- cross-package entrypoints that are intentionally thin
+
+## Runtime Pillars
+
+- `igniter-contracts`
+  canonical embedded kernel: DSL, compile/runtime spine, profiles, execution,
+  diagnostics, extension seams
+- `igniter-extensions`
+  packs, language additions, tooling, operational behavior, and domain behavior
+  over `igniter-contracts`
+- `igniter-application`
+  contracts-native local runtime host: config, providers, services, loaders,
+  schedulers, host adapters, boot lifecycle
+- `igniter-ai`
+  provider-neutral AI execution: request/response envelopes, provider clients,
+  credentials-aware configuration, fake/live/recorded modes, transcripts,
+  usage, errors, and replay seams
+- `igniter-agents`
+  agent runtime semantics over contracts and AI: agent definitions, runs,
+  turns, traces, tool-call evidence, and single-turn assistant execution
+- `igniter-hub`
+  local capsule catalog discovery and transfer bundle metadata; applications
+  still install through `igniter-application` transfer APIs
+- `igniter-cluster`
+  contracts-native distributed runtime: remote execution, routing, admission,
+  placement, peer registry, topology, distributed diagnostics
+- `igniter-ledger`
+  experimental contract-native hot fact engine: immutable facts, time-travel,
+  access paths, reactive invalidation, retention/compaction, LedgerServer
+  transport, and future hot/cold sync experiments
+- `igniter-durable-model`
+  experimental typed Record/History facade over `igniter-ledger`; owns
+  app-facing Store/History ergonomics and pressure from Companion manifests,
+  while avoiding core persistence API promises
+
+## Planned Runtime Packages
+
+- richer agent memory/context, handoff, human gates, contracts-first tool
+  execution, and supervisor vocabulary
+- stable contract persistence capability may still graduate later through
+  `igniter-extensions` / `igniter-application` / future `igniter-persistence`;
+  current `igniter-ledger` and `igniter-durable-model` remain pressure packages, not
+  final public persistence API
+
+## Current Supporting Packages
+
+- `igniter-mcp-adapter`
+  MCP adapter over contracts-native tooling and host integration
+- `igniter-web`
+  supporting web/UI package; active, but not a runtime pillar
+
+## Supporting Lanes
+
+- `legacy`
+  reference-only implementation material until deletion
+- adapter packages
+  MCP, HTTP, IDE, transport, protocol, and external integration surfaces
+- framework/plugin packages
+  Rails and other host-specific integrations
+- frontend packages
+  human-authored UI surfaces
+
+## Placement Heuristics
+
+- Put code in `igniter-contracts` if it defines canonical embedded graph
+  semantics, service execution protocols, or kernel extension seams.
+- Put code in `igniter-extensions` if it is optional behavior, tooling, or
+  domain vocabulary over the contracts kernel. Language-changing DSL packs such
+  as observable branching, formulas, scaling, and scoring primitives also live
+  here.
+- Put code in `igniter-application` if it is about local runtime hosting,
+  providers, services, boot, config, loading, or scheduling.
+- Put early contract-persistence experiments in `igniter-extensions` when they
+  add optional contract DSL/semantics, or in `igniter-application` when they
+  are app-host/back-end boundary behavior. Do not promote a separate package
+  until the target plan has repeated implementation evidence.
+- Put code in `igniter-cluster` if the network is part of the execution model.
+- Put immutable fact log, time-travel, access path, retention, LedgerServer,
+  sync-hub, and transport-backend experiments in `igniter-ledger`; do not put
+  contract business logic execution there.
+- Put app-facing generated Record/History classes, receipts, manifest-to-store
+  facades, and Companion pressure adapters in `igniter-durable-model`; do not put
+  core DSL promotion there.
+- Put provider clients, model envelopes, transcripts, usage, and replay seams in
+  `igniter-ai`.
+- Put agent loops, run state, tool policy, memory/context, handoff, and human
+  gates in `igniter-agents`.
+- Put capsule catalog discovery and bundle metadata in `igniter-hub`; keep
+  verification, intake, apply, receipts, and installed-capsule registries in
+  `igniter-application`.
+- Put transport and protocol work in adapter packages unless it is truly a
+  cluster semantic concern.
+- Touch legacy packages only for reference, parity, migration, or retirement
+  cleanup.
+- Put package-specific user docs next to the package README.
+
+## Explicit Non-Goals
+
+- do not treat `server` as a primary runtime pillar
+- do not treat stack orchestration as the default local app model
+- do not keep growing legacy packages as if they were still the target

data/docs/guide/README.md

@@ -0,0 +1,77 @@
+# Igniter Guide
+
+Use this section for user-facing documentation: learning the framework, choosing
+entrypoints, configuring runtime behavior, and building applications on top of
+Igniter.
+
+Current loading guidance:
+
+- prefer `require "igniter"` for embedded/default usage
+- prefer contracts-facing entrypoints when you are evaluating the migration path
+- use package README files for package-specific entrypoints
+- treat legacy entrypoints as private/reference context, not onboarding
+
+Pre-v1 status: Igniter intentionally does not promise backward compatibility or
+a stable public API yet. Public docs describe the current direction, not a
+compatibility contract.
+
+## What Belongs Here
+
+- getting started and first contract/app flows
+- public API and entrypoint guidance
+- how-to guides and cookbook material
+- configuration and operational usage
+- examples and package selection guidance
+
+## Canonical Guide Docs
+
+- [Top-level README](../../README.md)
+- [Getting Started](./getting-started.md)
+- [API And Runtime](./api-and-runtime.md)
+- [Contract Class DSL](./contract-class-dsl.md)
+- [Igniter Lang Foundation](./igniter-lang-foundation.md)
+- [Application Capsules](./application-capsules.md)
+- [Application Showcase Portfolio](./application-showcase-portfolio.md)
+- [Interactive App Structure](./interactive-app-structure.md)
+- [How-Tos](./how-tos.md)
+- [Configuration](./configuration.md)
+- [Credentials](./credentials.md)
+- [Deployment Modes](./deployment-modes.md)
+- [Integrations](./integrations.md)
+- [Distributed Workflows](./distributed-workflows.md)
+- [Core Runtime Features](./core-runtime-features.md)
+- [AI And Tool Surfaces](./ai-and-tools.md)
+- [Embedded Kernel](./core.md)
+- [App](./app.md)
+- [Cluster](./cluster.md)
+- [CLI](./cli.md)
+- [Store Adapters](./store-adapters.md)
+- [Contract Persistence Target Plan](../dev/contract-persistence-target-plan.md)
+
+## Core Guide References
+
+- [Concepts](../concepts/README.md)
+- [Igniter Concepts](../concepts/igniter.md)
+- [Examples](../../examples/README.md)
+- [Application Showcase Portfolio](./application-showcase-portfolio.md)
+
+## Package-Level Docs
+
+Package-specific quick reference should live next to the gem that owns the
+surface:
+
+- [`packages/igniter-contracts/README.md`](../../packages/igniter-contracts/README.md)
+- [`packages/igniter-embed/README.md`](../../packages/igniter-embed/README.md)
+- [`packages/igniter-application/README.md`](../../packages/igniter-application/README.md)
+- [`packages/igniter-cluster/README.md`](../../packages/igniter-cluster/README.md)
+- [`packages/igniter-web/README.md`](../../packages/igniter-web/README.md)
+- [`packages/igniter-extensions/README.md`](../../packages/igniter-extensions/README.md)
+- [`packages/igniter-mcp-adapter/README.md`](../../packages/igniter-mcp-adapter/README.md)
+
+Cross-package narratives and tutorials stay here in `docs/guide/`.
+
+## Legacy Boundary
+
+Legacy deep references are private working material under `playgrounds/docs/`.
+Public onboarding should start from the current guide, package READMEs,
+examples, and application showcase path.

data/docs/guide/ai-and-tools.md

@@ -0,0 +1,33 @@
+# AI And Tool Surfaces
+
+Use this page when you need optional AI-facing, agent-facing, or tool-facing
+surfaces around contracts.
+
+Public AI and agent APIs are not stable before v1. Current examples may prove
+the shape locally; reusable provider and agent behavior should graduate into
+`igniter-ai` and `igniter-agents`.
+
+## Current Surface Areas
+
+- tools for callable operations and tool schemas
+- skills for multi-step callable sub-agents
+- channels for transport-neutral outbound delivery
+- transcription for audio-to-text pipelines
+
+## Practical Split
+
+- use a tool for one atomic callable operation
+- use a skill for a bounded multi-step callable unit
+- use a channel for outbound delivery/notification
+- use transcription when audio becomes input to a graph
+
+## Reading Path
+
+- [Guide: How-Tos](./how-tos.md)
+- [Guide: Integrations](./integrations.md)
+- [`packages/igniter-extensions/README.md`](../../packages/igniter-extensions/README.md)
+- [`packages/igniter-mcp-adapter/README.md`](../../packages/igniter-mcp-adapter/README.md)
+- [AI And Agents Target Plan](../dev/ai-agents-target-plan.md)
+
+Historical AI/tool references are private working material under
+`playgrounds/docs/`.

data/docs/guide/api-and-runtime.md

@@ -0,0 +1,38 @@
+# API And Runtime
+
+Use this index when you already understand the basic idea and want the public
+surface area.
+
+## Canonical Public Reads
+
+- [Contract Class DSL](./contract-class-dsl.md)
+- [Core Runtime Features](./core-runtime-features.md)
+- [Getting Started](./getting-started.md)
+
+## Layer Entry Points
+
+- [Core](./core.md)
+- [App](./app.md)
+- [Cluster](./cluster.md)
+
+Operating modes to keep in mind:
+
+- `Embed` / contracts-first local runtime
+- `Application` / local host profile over embed
+- `Cluster` / distributed runtime over embed/application
+
+## Focused Topics
+
+- [Contract Class DSL](./contract-class-dsl.md)
+- [Igniter Lang Foundation](./igniter-lang-foundation.md)
+- [Store Adapters](./store-adapters.md)
+- [Deployment Modes](./deployment-modes.md)
+
+## Package Quick Reference
+
+Package-specific entrypoints live next to the owning gem:
+
+- [`packages/igniter-contracts/README.md`](../../packages/igniter-contracts/README.md)
+- [`packages/igniter-embed/README.md`](../../packages/igniter-embed/README.md)
+- [`packages/igniter-application/README.md`](../../packages/igniter-application/README.md)
+- [`packages/igniter-cluster/README.md`](../../packages/igniter-cluster/README.md)

data/docs/guide/app.md

@@ -0,0 +1,45 @@
+# App
+
+Use this section when Igniter becomes the runtime shape of an application, not
+only an embedded contract kernel.
+
+## Current Direction
+
+The target application model is contracts-native:
+
+- application capsules are the portability boundary
+- app-local code stays inside the app that owns it
+- optional web/UI surfaces live under the app, usually through `igniter-web`
+- stack-level shared code is reserved for code that is truly shared
+- hardcoded HTML strings in Ruby are not the recommended frontend path
+
+For new work, start with [Application Capsules](./application-capsules.md).
+For small interactive apps that combine `igniter-application` and
+`igniter-web`, use [Interactive App Structure](./interactive-app-structure.md).
+
+## Runtime Shape
+
+The preferred app/runtime shape is:
+
+- `stack.rb` defines apps and mounts
+- `stack.yml` defines server defaults, persistence, and optional node profiles
+- `bin/start`, `bin/dev`, and `bin/console` are the runtime entry points
+- `Igniter::Stack` owns mounted coordination
+- `Igniter::App` stays a portable mounted module
+
+Graduate to cluster behavior only when distributed execution is actually
+needed.
+
+## First Reads
+
+- [Application Capsules](./application-capsules.md)
+- [Interactive App Structure](./interactive-app-structure.md)
+- [Application Showcase Portfolio](./application-showcase-portfolio.md)
+- [Application Target Plan](../dev/application-target-plan.md)
+- [Igniter Web Target Plan](../dev/igniter-web-target-plan.md)
+- [CLI](./cli.md)
+- [Configuration](./configuration.md)
+- [Integrations](./integrations.md)
+
+Legacy deep references and older app/stack notes are private working material
+under `playgrounds/docs/`.

data/docs/guide/application-capsules.md

@@ -0,0 +1,139 @@
+# Application Capsules
+
+Application capsules are the copyable unit for Igniter apps. A capsule keeps
+contracts, services, optional web surfaces, imports, exports, and review
+metadata local to one application boundary.
+
+Use capsules when an app should be understandable before it is loaded, mounted,
+copied, or connected to a larger host.
+
+## Shape
+
+Small capsules stay sparse: create only the folders the app owns.
+
+```ruby
+capsule = Igniter::Application.capsule(:operator, root: "apps/operator") do
+  layout :capsule
+  groups :contracts, :services
+
+  export :resolve_incident,
+         kind: :contract,
+         target: "Contracts::ResolveIncident"
+
+  import :incident_runtime,
+         kind: :service,
+         from: :host,
+         capabilities: [:incidents]
+end
+
+blueprint = capsule.to_blueprint
+```
+
+The explicit data form is equally valid:
+
+```ruby
+blueprint = Igniter::Application.blueprint(
+  name: :operator,
+  root: "apps/operator",
+  layout_profile: :capsule,
+  groups: %i[contracts services]
+)
+```
+
+Use the data form for generators and diffs. Use the DSL form for human-edited
+application code.
+
+## Web Is Optional
+
+A capsule can be web-capable without becoming a web framework object.
+`igniter-application` accepts plain surface metadata; `igniter-web` owns
+screens, routes, components, and rendering details.
+
+```ruby
+blueprint = Igniter::Application.blueprint(
+  name: :operator,
+  root: "apps/operator",
+  layout_profile: :capsule,
+  groups: %i[contracts services],
+  web_surfaces: [:operator_console]
+)
+```
+
+This keeps non-web and web-capable apps in the same application vocabulary.
+
+## Reports
+
+Capsule reports are read-only inspection output. They summarize:
+
+- identity and layout profile
+- active and known groups
+- planned sparse and complete paths
+- imports and exports
+- optional features, flows, and supplied surface metadata
+
+Reports do not load constants, create files, execute contracts, mount web
+surfaces, or boot an app.
+
+```ruby
+report = blueprint.capsule_report
+report.to_h
+```
+
+## Transfer
+
+Capsule transfer is review-first. The lifecycle is deliberately explicit:
+
+1. inspect the capsule with `capsule_report`
+2. review physical files with `transfer_inventory`
+3. check readiness with `transfer_readiness`
+4. build a `transfer_bundle_plan`
+5. write and verify a transfer bundle
+6. preview destination intake
+7. dry-run apply operations
+8. commit only reviewed file operations
+9. verify the applied transfer
+10. close with `transfer_receipt`
+11. optionally record the result in an installed-capsule registry
+
+Only the explicit committed apply step mutates the destination filesystem.
+Host wiring, load paths, provider registration, web route activation, contract
+execution, and cluster placement remain outside transfer.
+
+Installed-capsule registries are application state, not hub state. A hub can
+discover a candidate bundle, but `igniter-application` owns the receipt-backed
+record that says what was installed, whether it is complete, and which source
+and version produced it. The file-backed registry keeps current state separate
+from append-only history so future upgrade, rollback, and audit flows can build
+on the same receipt trail.
+
+Runnable end-to-end example:
+
+```bash
+ruby examples/application/capsule_transfer_end_to_end.rb
+```
+
+## Activation Boundary
+
+A complete transfer receipt means reviewed files landed and verified. It does
+not mean the receiving host activated the app.
+
+Host activation is a separate review lane:
+
+- `host_activation_readiness`
+- `host_activation_plan`
+- `verify_host_activation_plan`
+- optional ledger-backed acknowledgement receipts
+
+The current ledger path records reviewed confirmations. It is not live host
+mutation and does not boot providers, bind routes, execute contracts, or touch a
+cluster.
+
+## Examples
+
+- [`examples/application/capsule_composition.rb`](../../examples/application/capsule_composition.rb)
+- [`examples/application/capsule_assembly_plan.rb`](../../examples/application/capsule_assembly_plan.rb)
+- [`examples/application/capsule_transfer_end_to_end.rb`](../../examples/application/capsule_transfer_end_to_end.rb)
+- [`examples/application/capsule_host_activation_readiness.rb`](../../examples/application/capsule_host_activation_readiness.rb)
+
+For app/web conventions, continue with
+[Interactive App Structure](./interactive-app-structure.md).

data/docs/guide/application-showcase-portfolio.md

@@ -0,0 +1,181 @@
+# Application Showcase Portfolio
+
+This guide is the current application showcase map for Igniter. Use it when you
+want to evaluate the richer contracts-native examples as products, not only as
+small API snippets.
+
+The portfolio has five current applications:
+
+- Companion: ready-to-go personal assistant shell.
+- Lense: local codebase intelligence.
+- Chronicle: architecture decision review.
+- Scout: local-source research synthesis.
+- Dispatch: incident command and handoff.
+
+Each application is intentionally offline, one-process, and reproducible. They
+exercise `igniter-application`, `igniter-contracts`, `igniter-extensions`, and
+`igniter-web` through app-local structure. They do not define a public
+interactive app API.
+
+## What The Portfolio Proves
+
+The showcases demonstrate the same serious application loop:
+
+- app-owned services load local inputs, own mutable session state, and emit
+  deterministic evidence artifacts
+- one contracts-native graph computes the core analysis, readiness, or payload
+- command routes return app-local success/refusal results and record action
+  facts
+- one detached snapshot feeds the Web surface, `/events`, smoke output, and
+  manual inspection
+- `/report` or `/receipt` exposes an app-owned evidence artifact
+- smoke runs prove success, refusal, endpoint parity, and mutation boundaries
+
+This repetition is a copyable convention. It is not yet a framework contract,
+shared command result class, snapshot API, route DSL, marker DSL, UI kit,
+receipt/report API, or `Igniter.interactive_app` facade.
+
+## Showcase Matrix
+
+| Showcase | Purpose | Workflow | Packages exercised | Evidence artifact | Mutation boundary | Smoke | Manual server |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Companion | Personal assistant shell for ordinary users. | Credentials setup -> reminders/trackers/countdowns -> body battery -> daily plan. | `igniter-application`, `igniter-contracts`, `igniter-extensions`, `igniter-ai`, `igniter-web`. | Setup state and deterministic daily summary. | SQLite app store; live AI remains explicit opt-in. | `ruby examples/application/companion_poc.rb` | `ruby examples/application/companion_poc.rb server` |
+| Lense | Codebase intelligence for a local Ruby project. | Scan project -> health findings -> guided issue session -> analysis report. | `igniter-application`, `igniter-contracts`, `igniter-extensions`, `igniter-web`. | `LenseAnalysisReceipt` through `/report`. | Reads an explicit sample project and proves no scanned-project mutation. | `ruby examples/application/lense_poc.rb` | `ruby examples/application/lense_poc.rb server` |
+| Chronicle | Decision compass for architecture proposals. | Proposal scan -> decision conflicts -> sign-off/refusal -> decision receipt. | `igniter-application`, `igniter-contracts`, `igniter-extensions`, `igniter-web`. | `DecisionReceipt` through `/receipt`. | Reads proposal/decision fixtures and writes runtime sessions/actions/receipts only to workdir. | `ruby examples/application/chronicle_poc.rb` | `ruby examples/application/chronicle_poc.rb server` |
+| Scout | Local-source research workspace. | Topic + local sources -> findings -> direction checkpoint -> research receipt. | `igniter-application`, `igniter-contracts`, `igniter-extensions`, `igniter-web`. | `ResearchReceipt` through `/receipt`. | Reads local source fixtures and writes runtime sessions/actions/receipts only to workdir. | `ruby examples/application/scout_poc.rb` | `ruby examples/application/scout_poc.rb server` |
+| Dispatch | Incident command and handoff. | Seeded incident events -> triage/routing -> assignment checkpoint -> incident receipt. | `igniter-application`, `igniter-contracts`, `igniter-extensions`, `igniter-web`. | `IncidentReceipt` through `/receipt`. | Reads incident/event/runbook/team fixtures and writes runtime sessions/actions/receipts only to workdir. | `ruby examples/application/dispatch_poc.rb` | `ruby examples/application/dispatch_poc.rb server` |
+
+## Package Capability Map
+
+Each showcase keeps its domain logic local while exercising the same package
+roles:
+
+| Showcase | Application capability | Contracts capability | Web capability |
+| --- | --- | --- | --- |
+| Lense | App composition, scan service, issue-session commands, snapshot, report endpoint. | `CodebaseHealthContract` computes health score, findings, evidence refs, and report metadata. | Mounted dashboard/workbench with `/events`, `/report`, feedback, counters, findings, and activity markers. |
+| Chronicle | Proposal/decision stores, conflict session commands, sign-off/refusal state, receipt endpoint. | `DecisionReviewContract` computes conflicts, required sign-offs, readiness, and receipt payload. | Mounted decision compass with `/events`, `/receipt`, feedback, conflict evidence, sign-off/refusal, and activity markers. |
+| Scout | Source library, research session commands, checkpoint state, receipt endpoint. | `ResearchSynthesisContract` computes findings, contradictions, checkpoint readiness, citations, and synthesis payload. | Mounted research workspace with `/events`, `/receipt`, feedback, source/provenance, checkpoint, and activity markers. |
+| Dispatch | Incident library, triage session commands, assignment/escalation state, receipt endpoint. | `IncidentTriageContract` computes severity, suspected cause, routing options, readiness, and receipt payload. | Mounted command center with `/events`, `/receipt`, feedback, event/citation, routing, assignment, and activity markers. |
+
+## Web Review Map
+
+Each richer showcase has one mounted Arbre surface. The surface reads one
+app-owned snapshot through `MountContext`; `app.rb` owns command routes,
+redirect feedback, `/events`, and the evidence endpoint.
+
+| Showcase | Mounted surface | Surface marker | Evidence endpoint | Manual review focus |
+| --- | --- | --- | --- | --- |
+| Lense | `web/lense_dashboard.rb` as `:lense_dashboard`. | `data-ig-poc-surface="lense_dashboard"` | `/report` | Scan summary, findings, evidence refs, issue-session actions, report validity, and no scanned-project mutation. |
+| Chronicle | `web/decision_compass.rb` as `:decision_compass`. | `data-ig-poc-surface="chronicle_decision_compass"` | `/receipt` | Proposal context, conflict evidence, sign-off/refusal state, decision receipt validity, and fixture no-mutation. |
+| Scout | `web/research_workspace.rb` as `:research_workspace`. | `data-ig-poc-surface="scout_research_workspace"` | `/receipt` | Topic, sources, citations, provenance, findings, contradictions, checkpoint state, research receipt validity, and fixture no-mutation. |
+| Dispatch | `web/command_center.rb` as `:command_center`. | `data-ig-poc-surface="dispatch_command_center"` | `/receipt` | Incident events, severity, routing rationale, assignment/escalation checkpoint, handoff receipt validity, and fixture no-mutation. |
+
+During manual review, inspect the browser page and these companion endpoints:
+
+- `/events` should agree with the visible state because both render from the
+  same detached app snapshot.
+- `/report` or `/receipt` should expose the app-owned evidence artifact when
+  the workflow reaches its checkpoint.
+- feedback should appear through query-string redirect state and render with
+  `data-ig-feedback` plus an app-local `data-feedback-code`.
+- recent activity should render from the same snapshot and use
+  `data-ig-activity` plus app-local action metadata.
+- command controls should expose app-local `data-action` values.
+- domain records and counters should expose explicit app-local `data-`
+  attributes for smoke and browser inspection.
+
+These markers are inspection seams, not a public marker DSL. Surface names,
+feedback codes, action names, endpoint labels, CSS direction, and panel
+grouping remain local to each showcase.
+
+## Run The Portfolio
+
+Run the full active examples catalog:
+
+```bash
+ruby examples/run.rb smoke
+```
+
+Run an individual showcase through the catalog:
+
+```bash
+ruby examples/run.rb run application/lense_poc
+ruby examples/run.rb run application/chronicle_poc
+ruby examples/run.rb run application/scout_poc
+ruby examples/run.rb run application/dispatch_poc
+```
+
+Run an individual showcase directly:
+
+```bash
+ruby examples/application/lense_poc.rb
+ruby examples/application/chronicle_poc.rb
+ruby examples/application/scout_poc.rb
+ruby examples/application/dispatch_poc.rb
+```
+
+Open a manual browser surface:
+
+```bash
+ruby examples/application/lense_poc.rb server
+ruby examples/application/chronicle_poc.rb server
+ruby examples/application/scout_poc.rb server
+ruby examples/application/dispatch_poc.rb server
+```
+
+Each server command prints a local URL. Server mode is example scaffolding for
+manual review, not production server behavior.
+
+Use in-process smoke runs as the default proof. Manual browser review is useful
+for evaluating the mounted screens, but the portfolio does not require browser
+automation, live transport, a production server, auth, persistence, scheduler,
+connectors, or LLM/provider integration.
+
+## Evidence To Inspect
+
+For each showcase, inspect three surfaces together:
+
+- HTML surface: the mounted `igniter-web` screen with stable app-local
+  `data-` markers.
+- `/events`: the text read model that mirrors the same app-owned snapshot.
+- `/report` or `/receipt`: the evidence artifact emitted by the app.
+
+The smoke output should include markers for:
+
+- the first successful command path
+- at least one refusal path
+- recent action facts
+- `/events` parity with the Web surface snapshot
+- receipt/report validity
+- fixture or target no-mutation
+
+## Application Structure Convention
+
+Use the showcase layout as a convention for new application experiments:
+
+- `app.rb` is the visible composition boundary.
+- `contracts/` contains the deterministic contracts-native graph.
+- `services/` owns loading, state, commands, and snapshots.
+- `reports/` owns receipt/report rendering when the workflow has evidence to
+  emit.
+- `web/` owns the local mounted surface.
+- the launcher script owns smoke and optional `server` mode.
+
+Keep domain names and repeated shapes local until package extraction is
+explicitly justified. In particular, keep command result classes, snapshot
+fields, feedback codes, route names, marker names, receipt payload keys,
+fixture schemas, thresholds, and readiness rules inside the app.
+
+For the detailed copyable convention, see
+[Interactive App Structure](./interactive-app-structure.md).
+
+## Legacy Boundary
+
+Legacy material is private/reference context, not the current onboarding path.
+Start from the current packages, this portfolio guide, the interactive app
+structure guide, and the four showcase READMEs:
+
+- [`examples/application/lense/README.md`](../../examples/application/lense/README.md)
+- [`examples/application/chronicle/README.md`](../../examples/application/chronicle/README.md)
+- [`examples/application/scout/README.md`](../../examples/application/scout/README.md)
+- [`examples/application/dispatch/README.md`](../../examples/application/dispatch/README.md)