igniter 0.5.0 → 0.5.2

data/docs/dev/igniter-web-dsl-sketch.md

@@ -0,0 +1,151 @@
+# Igniter Web DSL Sketch
+
+This note captures the current authoring-first direction for `igniter-web`.
+
+It complements:
+
+- [Igniter Web Target Plan](./igniter-web-target-plan.md)
+
+## DSL Thesis
+
+Design `igniter-web` from the shape we want users to write, not from the
+internal routing primitives first.
+
+The package should feel:
+
+- compact
+- expressive
+- low-boilerplate
+- pleasant to scan
+- friendly to long-lived, stream-heavy, non-CRUD web surfaces
+
+## Current Preferred Feel
+
+The intended tone is closer to:
+
+- Sinatra for compactness
+- Rails for pleasant conventions
+- Igniter for contracts/process/stream semantics
+
+Not:
+
+- a controller-heavy ceremony-first framework
+- an ORM-centered CRUD shell
+
+## Initial Authoring Shape
+
+The first DSL pass should make examples like this feel natural:
+
+```ruby
+app = Igniter::Web.application do
+  root title: "Operator" do
+    main class: "shell" do
+      h1 "Operator"
+      para "Cluster is healthy"
+    end
+  end
+
+  page "/projects/:id", title: "Project" do
+    main do
+      h1 assigns[:project_name]
+      para assigns[:status]
+    end
+  end
+
+  command "/projects/:id/advance", to: Contracts::AdvanceProject
+  stream "/projects/:id/events", to: Projections::ProjectEvents
+end
+```
+
+This is intentionally more compact than:
+
+- explicit controller classes
+- explicit template file wiring for every first page
+- multiple ceremony objects before the screen can exist
+
+For agent-managed and process-oriented surfaces, the DSL should also support
+screen intent that can be composed before rendering:
+
+```ruby
+screen :plan_review, intent: :human_decision do
+  title "Plan review"
+
+  show :plan_summary
+  show :risk_panel
+  compare :current_plan, :proposed_plan
+
+  action :approve, run: Contracts::ApprovePlan
+  action :revise, run: Contracts::RequestRevision
+  chat with: Agents::ProjectLead
+
+  compose with: :decision_workspace
+end
+```
+
+## DSL Priorities
+
+Prioritize these authoring wins early:
+
+- `root` and `page` as first-class route + page sugar
+- inline page blocks
+- easy promotion path from inline page to dedicated page class
+- Arbre-backed HTML authoring
+- simple layout defaults
+- compact route declarations for `command`, `query`, `stream`, and `webhook`
+
+## Promotion Path
+
+The DSL should support growth from tiny apps to richer apps without punishing
+the simple case.
+
+Start small:
+
+```ruby
+page "/chat", title: "Chat" do
+  h1 "Chat"
+end
+```
+
+Promote later:
+
+```ruby
+class ChatPage < Igniter::Web::Page
+  title "Chat"
+
+  body do
+    main do
+      h1 "Chat"
+    end
+  end
+end
+
+page "/chat", to: ChatPage
+```
+
+That gives the package a useful spectrum:
+
+- inline for small surfaces
+- classes for reusable or larger surfaces
+
+## First-Class Authoring Objects
+
+The current DSL lane should revolve around:
+
+- `Application`
+- `Page`
+- `Component`
+- `Api`
+- `Record`
+
+The shape is intentionally:
+
+- `Application` for route drawing and web composition
+- `Page` for full-screen HTML surfaces
+- `Component` for reusable UI vocabulary
+- `Api` for contracts-first transport declarations
+- `Record` for optional persistence convenience
+
+## Working Rule
+
+If a proposed API makes small web surfaces longer, noisier, or more ceremonial
+without buying a real capability, it is probably the wrong default DSL.

data/docs/dev/igniter-web-target-plan.md

@@ -0,0 +1,56 @@
+# Igniter Web Target Plan
+
+This note defines the current public target for `igniter-web`.
+
+## Thesis
+
+`igniter-web` should be the contracts-first web layer for Igniter applications.
+It should make app-owned state visible and operable without turning Igniter into
+a CRUD-first Rails clone.
+
+The primary surfaces are:
+
+- dashboards
+- operator workspaces
+- command/refusal flows
+- chats and streams when they are backed by explicit app contracts
+- receipt, report, and event review screens
+
+## Ownership
+
+`igniter-web` owns:
+
+- mounted web surfaces
+- request handling for example/review surfaces
+- screen composition primitives
+- `MountContext`
+- surface structure and surface manifest metadata
+
+It does not own:
+
+- application boot
+- provider or service registration
+- contract registration
+- app mutation policy
+- production deployment behavior
+- cluster placement
+
+Those remain application, host, or cluster concerns.
+
+## Current Proof
+
+The current proof comes from Lense, Chronicle, Scout, and Dispatch. Each app
+mounts one web surface, renders from an app-owned snapshot, exposes `/events`,
+and emits `/report` or `/receipt` evidence.
+
+Public review path:
+
+- [Application Showcase Portfolio](../guide/application-showcase-portfolio.md)
+- [Application Showcase Portfolio](../guide/application-showcase-portfolio.md)
+- [Interactive App Structure](../guide/interactive-app-structure.md)
+
+## Extraction Rule
+
+Keep repeated web shapes local until the showcase portfolio proves a stable
+abstraction. Public package APIs should be promoted only when they preserve
+clear ownership between application state, command handling, and web rendering.

data/docs/dev/mcp-adapter-package-spec.md

@@ -0,0 +1,81 @@
+# MCP Adapter Package
+
+## Purpose
+
+`igniter-mcp-adapter` is the transport-facing package that sits on top of the
+tooling semantics already defined in `igniter-extensions`.
+
+Its job is not to invent new tools. Its job is to adapt the existing catalog
+and invocation surface into a package that can host:
+
+- a real MCP server
+- CLI wrappers
+- editor integrations
+- agent-facing bridges
+
+## Source Of Truth
+
+The semantic source of truth stays in `igniter-extensions`:
+
+- `Igniter::Extensions::Contracts.mcp_tools`
+- `Igniter::Extensions::Contracts.mcp_call(...)`
+- `Igniter::Extensions::Contracts.mcp_creator_session(...)`
+
+The adapter package should treat those as authoritative.
+
+## Why A Separate Package
+
+This split gives us scalability by default:
+
+- `igniter-extensions` owns debug/creator/tooling semantics
+- `igniter-mcp-adapter` owns transport/runtime integration concerns
+- future adapters can reuse the same semantic surface without duplicating logic
+
+That means we can add more than one adapter later:
+
+- MCP server adapter
+- CLI adapter
+- IDE adapter
+- web/dev console adapter
+
+## Package Boundary
+
+`igniter-mcp-adapter`:
+
+- depends on `igniter-extensions`
+- should not depend directly on `igniter-contracts` internals
+- should not define new creator/debug semantics
+- should not become a second tool catalog source
+
+## Minimal Public Surface
+
+Near-term public surface:
+
+- `Igniter::MCP::Adapter.tool_catalog`
+- `Igniter::MCP::Adapter.tool_names`
+- `Igniter::MCP::Adapter.tool_definition(name)`
+- `Igniter::MCP::Adapter.invoke(name, ...)`
+- `Igniter::MCP::Adapter.creator_session(...)`
+
+This is intentionally thin. It keeps the adapter package honest.
+
+## Current State
+
+This is already real in the monorepo:
+
+- `Igniter::MCP::Adapter`
+  thin delegation over the semantic tooling surface
+- `Igniter::MCP::Adapter::Server`
+  transport-ready tool definitions and tool result envelopes
+- `Igniter::MCP::Adapter::Host`
+  stdio JSON-RPC host over the server wrapper
+
+So this package is no longer only a design placeholder.
+
+## Next Likely Steps
+
+1. decide whether we want additional MCP surfaces like `resources/list` or
+   `prompts/list`, or whether tools-only is the right first stable contract
+2. keep request validation aligned with generated schemas
+3. only add transport/runtime concerns that do not create a second semantic source
+4. use this package as the only place where MCP transport specifics evolve

data/docs/dev/module-system.md

@@ -0,0 +1,46 @@
+# Module System
+
+Igniter's public module map is pre-v1 and package-first.
+
+## Current Axes
+
+- `igniter-contracts`
+  embedded graph kernel: DSL, compilation, execution, diagnostics
+- `igniter-extensions`
+  optional packs over contracts: dataflow, differential, reporting, tooling
+- `igniter-embed`
+  host integration and configuration, especially Rails-style embedding
+- `igniter-application`
+  local app profile, providers, services, capsules, transfer, activation review
+- `igniter-web`
+  contracts-first web surfaces and app-local interactive screens
+- `igniter-cluster`
+  distributed routing, placement, ownership, health, and remediation
+- `igniter-mcp-adapter`
+  MCP-facing tool catalog and invocation surface
+
+## Rules
+
+- Lower layers must not know about upper layers.
+- Optional behavior should be an explicit pack, not hidden boot mutation.
+- Integrations adapt Igniter to a host; they are not runtime layers.
+- Web owns rendering; application owns app profile and lifecycle.
+- Cluster owns distribution; contracts stay local-first and host-agnostic.
+
+## Rails Boundary
+
+Rails embedding should use `igniter-embed` / Rails integration surfaces. It
+should not implicitly load application hosting, web rendering, or cluster
+coordination.
+
+## Placement Heuristic
+
+Ask in this order:
+
+1. Is it executable graph semantics? Put it in `igniter-contracts`.
+2. Is it optional reusable behavior over contracts? Put it in
+   `igniter-extensions`.
+3. Is it host integration? Put it in `igniter-embed` or a specific adapter.
+4. Is it local app runtime? Put it in `igniter-application`.
+5. Is it human/browser interaction? Put it in `igniter-web`.
+6. Is it distributed execution or coordination? Put it in `igniter-cluster`.

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/`.