igniter 0.5.0 → 0.5.1

data/README.md

@@ -1,95 +1,41 @@
 # Igniter
 
-Igniter is a Ruby gem for expressing business logic as a validated dependency graph and executing that graph with:
-
-- lazy output resolution and selective cache invalidation
-- typed input validation with defaults and required fields
-- nested contract composition with isolated child executions
-- declarative routing (`branch`) and fan-out (`collection`)
-- distributed workflows: `await` events across process boundaries
-- multi-node deployments via `igniter-server` and the `remote:` DSL
-- LLM compute nodes with Ollama, Anthropic, and OpenAI providers
-- Rails integration: ActiveJob, ActionCable, webhook handlers, generators
-- runtime auditing, diagnostics reports, and reactive side effects
-- graph and runtime introspection (text, Mermaid)
-- ergonomic DSL helpers: `const`, `lookup`, `map`, `project`, `aggregate`, `guard`, `export`, `expose`, `effect`, `on_success`, `scope`, `namespace`
-- `Igniter::Application` — application scaffold with YAML config, autoloading, scheduler, and `igniter-server new` generator
-- capability-based security: declare executor resource requirements, enforce `Policy` at runtime
-- temporal contracts: reproducible historical execution via an explicit `as_of` time input
-- content-addressed computation: `pure` executors cached by input fingerprint across executions and processes
+Igniter is a Ruby framework for building business logic as validated dependency graphs.
 
-## Installation
+At the center is a small, strict idea:
 
-```ruby
-gem "igniter"
-```
+- describe dependencies explicitly
+- validate the graph before runtime
+- resolve only what is needed
+- keep the runtime observable
 
-## Quick Start
-
-```ruby
-require "igniter"
-
-class PriceContract < Igniter::Contract
-  define do
-    input :order_total, type: :numeric
-    input :country,     type: :string
-    input :vat_rate,    type: :numeric, default: 0.2
-
-    compute :effective_vat_rate, depends_on: %i[country vat_rate] do |country:, vat_rate:|
-      country == "UA" ? vat_rate : 0.0
-    end
+From there, Igniter scales by layers instead of by reinvention:
 
-    compute :gross_total, depends_on: %i[order_total effective_vat_rate] do |order_total:, effective_vat_rate:|
-      order_total * (1 + effective_vat_rate)
-    end
+- **Core** for contracts, compilation, execution, diagnostics
+- **App** for a single-node runtime/profile
+- **Cluster** for capability-based distributed execution
+- **SDK** for optional packs such as AI, channels, tools, and data
 
-    output :gross_total
-  end
-end
+This README is an entrypoint, not the full reference. The reference now lives in
+[`docs/`](./docs/README.md), organized into [`guide`](./docs/guide/README.md),
+[`concepts`](./docs/concepts/README.md), [`current`](./docs/current/README.md),
+and [`dev`](./docs/dev/README.md).
 
-contract = PriceContract.new(order_total: 100, country: "UA")
-contract.result.gross_total   # => 120.0
+## Why Igniter
 
-contract.update_inputs(order_total: 150)
-contract.result.gross_total   # => 180.0
+Igniter is useful when your domain logic wants more structure than “service objects everywhere” but less ceremony than a full workflow engine.
 
-contract.diagnostics_text     # compact execution summary
-```
+You define a graph of inputs, computations, branches, collections, compositions, and outputs. Igniter compiles that graph, validates it, and gives you a runtime that is lazy, inspectable, and capable of growing from embedded usage to app hosting and then to a cluster.
 
-## Features
-
-- **Contracts**: declare inputs, compute nodes, outputs, and compositions in a validated graph.
-- **Compiler**: validate dependency graphs, types, and cycles before runtime; errors are surfaced at load time.
-- **Runtime**: cache resolved nodes and invalidate only affected downstream nodes on input change.
-- **Typed inputs**: validate types, defaults, and required fields at execution boundaries.
-- **Composition**: execute nested contracts with isolated child executions.
-- **Branch**: declarative routing — select one child contract from ordered cases at runtime.
-- **Collection**: declarative fan-out — run one child contract per item in an array.
-- **Distributed workflows**: `await` external events; resume via `deliver_event`.
-- **igniter-server**: host contracts as a TCP/Rack HTTP service; call remote contracts with the `remote:` DSL.
-- **LLM integration**: compute nodes powered by Ollama, Anthropic, or OpenAI providers.
-- **Rails integration**: Railtie, ActiveJob base class, ActionCable adapter, webhook controller mixin.
-- **Auditing**: collect execution timelines and snapshots.
-- **Diagnostics**: compact text, Markdown, or structured reports for triage.
-- **Reactive**: subscribe declaratively to runtime events with `effect`, `on_success`, `on_failure`.
-- **Introspection**: render graphs as text or Mermaid; inspect runtime state.
-- **Capabilities**: executors declare what resources they need (`:network`, `:database`, …); `Policy` denies them at runtime.
-- **Temporal contracts**: inject `as_of` time input automatically; replay any historical computation with the original timestamp.
-- **Content addressing**: `pure` executors get a universal cache key — identical inputs return a cached result across executions, processes, and deployments.
-- **Incremental dataflow**: `mode: :incremental` on collection nodes — only added/changed items run, unchanged items reuse cached results, removed items are retracted. O(change) not O(total).
-
-## Quick Start Recipes
-
-Runnable examples live in [`examples/`](examples) and are smoke-tested by `spec/igniter/example_scripts_spec.rb`.
-See [`examples/README.md`](examples/README.md) for a quick index and [`docs/PATTERNS.md`](docs/PATTERNS.md) for composable patterns.
-
-### 1. Basic Pricing Contract
+## A Tiny Example
 
 ```ruby
+require "igniter"
+
 class PriceContract < Igniter::Contract
   define do
     input :order_total, type: :numeric
-    input :country,     type: :string
+    input :country, type: :string
 
     compute :vat_rate, depends_on: [:country] do |country:|
       country == "UA" ? 0.2 : 0.0
@@ -103,622 +49,214 @@ class PriceContract < Igniter::Contract
   end
 end
 
-PriceContract.new(order_total: 100, country: "UA").result.gross_total
-# => 120.0
-```
-
-### 2. Nested Composition
-
-```ruby
-class CheckoutContract < Igniter::Contract
-  define do
-    input :order_total, type: :numeric
-    input :country,     type: :string
-
-    compose :pricing, contract: PriceContract, inputs: {
-      order_total: :order_total,
-      country:     :country
-    }
-
-    output :pricing
-  end
-end
-
-CheckoutContract.new(order_total: 100, country: "UA").result.pricing.gross_total
-# => 120.0
-```
-
-### 3. Diagnostics and Introspection
-
-```ruby
 contract = PriceContract.new(order_total: 100, country: "UA")
 contract.result.gross_total
-
-contract.result.states
-contract.result.explain(:gross_total)
-contract.diagnostics.to_h
-contract.diagnostics_text
-contract.diagnostics_markdown
-contract.audit_snapshot
-
-PriceContract.graph.to_text
-PriceContract.graph.to_mermaid
-```
-
-### 4. Machine-Readable Data
-
-```ruby
-contract.result.to_h       # => { gross_total: 120.0 }
-contract.result.as_json
-contract.execution.as_json
-contract.events.map(&:as_json)
-```
-
-### 5. Async Store and Resume
-
-```ruby
-class AsyncQuoteExecutor < Igniter::Executor
-  def call(order_total:)
-    defer(token: "quote-#{order_total}", payload: { kind: "pricing_quote" })
-  end
-end
-
-class AsyncPricingContract < Igniter::Contract
-  run_with runner: :store
-
-  define do
-    input :order_total, type: :numeric
-    compute :quote_total, depends_on: [:order_total], call: AsyncQuoteExecutor
-    compute :gross_total, depends_on: [:quote_total] do |quote_total:|
-      quote_total * 1.2
-    end
-    output :gross_total
-  end
-end
-
-contract     = AsyncPricingContract.new(order_total: 100)
-deferred     = contract.result.gross_total
-execution_id = contract.execution.events.execution_id
-
-resumed = AsyncPricingContract.resume_from_store(
-  execution_id, token: deferred.token, value: 150
-)
-resumed.result.gross_total  # => 180.0
+# => 120.0
 ```
 
-### 6. Ergonomic DSL
-
-```ruby
-class MarketingQuoteContract < Igniter::Contract
-  define do
-    input :service,  type: :string
-    input :zip_code, type: :string
-
-    const :vendor_id, "eLocal"
+## One Real Example
 
-    scope :routing do
-      map :trade_name, from: :service do |service:|
-        %w[heating cooling ventilation].include?(service.downcase) ? "HVAC" : service
-      end
-    end
+Imagine a post-call analysis pipeline for a call center.
 
-    scope :pricing do
-      lookup :trade, with: :trade_name do |trade_name:|
-        { name: trade_name, base_bid: 45.0 }
-      end
-    end
+The business task is simple to describe:
 
-    namespace :validation do
-      guard :zip_supported, with: :zip_code, in: %w[60601 10001], message: "Unsupported zip"
-    end
+- take a recording
+- transcribe it
+- extract structured facts
+- score the call
+- prepare CRM updates and supervisor follow-up
 
-    compute :quote, with: %i[vendor_id trade zip_code zip_supported] do |vendor_id:, trade:, zip_code:, zip_supported:|
-      zip_supported
-      { vendor_id: vendor_id, trade: trade[:name], zip_code: zip_code, bid: trade[:base_bid] }
-    end
-
-    expose :quote, as: :response
-  end
-
-  on_success :response do |value:, **|
-    puts "Persist #{value.inspect}"
-  end
-end
-```
-
-Matcher-style guard shortcuts:
+In Igniter, that stays one explicit graph:
 
 ```ruby
-guard :usa_only,          with: :country_code, eq: "USA",            message: "Unsupported country"
-guard :supported_country, with: :country_code, in: %w[USA CAN],      message: "Unsupported country"
-guard :valid_zip,         with: :zip_code,     matches: /\A\d{5}\z/, message: "Invalid zip"
-```
+require "igniter/cluster"
 
-### 7. Declarative Branching
-
-```ruby
-class DeliveryContract < Igniter::Contract
+class PostCallAnalysisContract < Igniter::Contract
   define do
-    input :country
-    input :order_total
-
-    branch :delivery_strategy, with: :country, inputs: {
-      country:     :country,
-      order_total: :order_total
-    } do
-      on "US", contract: USDeliveryContract
-      on "UA", contract: LocalDeliveryContract
-      default   contract: DefaultDeliveryContract
+    input :call_id, type: :string
+    input :audio_url, type: :string
+    input :recorded_at, type: :string
+
+    remote :transcript,
+           contract: "TranscribeCall",
+           query: { all_of: [:audio_transcription], tags: [:gpu] },
+           inputs: { audio_url: :audio_url }
+
+    remote :analysis,
+           contract: "AnalyzeCall",
+           query: { all_of: [:llm_inference] },
+           inputs: {
+             call_id: :call_id,
+             transcript: :transcript,
+             recorded_at: :recorded_at
+           }
+
+    compute :crm_patch, depends_on: [:analysis] do |analysis:|
+      {
+        disposition: analysis[:disposition],
+        sentiment: analysis[:sentiment],
+        next_action: analysis[:next_action],
+        escalation_required: analysis[:escalation_required]
+      }
     end
 
-    export :price, :eta, from: :delivery_strategy
+    output :analysis
+    output :crm_patch
   end
 end
 ```
 
-### 8. Declarative Collections
+Why this is interesting:
 
-```ruby
-class TechnicianBatchContract < Igniter::Contract
-  define do
-    input :technician_inputs, type: :array
+- the domain flow is still one contract, not a pile of queue handlers
+- transcription and analysis can land on different nodes with different capabilities
+- the cluster routes by capabilities, not by hard-coded machine roles
+- if one matching node disappears, the network can select another suitable peer without changing the contract
 
-    collection :technicians,
-               with: :technician_inputs,
-               each: TechnicianContract,
-               key:  :technician_id,
-               mode: :collect
+That is the general Igniter idea: keep the business graph stable, let the runtime grow from local execution to a capability-driven cluster.
 
-    output :technicians
-  end
-end
-```
+## The Levels
 
-In `mode: :collect`, an execution succeeds overall while items may individually fail:
+### 1. Core
 
-- `result.summary`       — collection-level status (`:partial_failure` when any item failed)
-- `result.items_summary` — compact per-item status hash
-- `result.failed_items`  — failed-item error details
-- `result.successes`     — hash of succeeded items only
+Start here if you want the kernel:
 
-See [`examples/collection_partial_failure.rb`](examples/collection_partial_failure.rb).
+- contract DSL
+- compiler and graph validation
+- lazy runtime and invalidation
+- diagnostics, events, introspection
 
-### 9. Distributed Contracts
+Read:
 
-Use `await` to suspend execution until an external event arrives. `correlate_by` identifies
-which execution should receive the event, so events can be delivered from any process:
+- [`docs/guide/core.md`](./docs/guide/core.md)
 
-```ruby
-class LeadWorkflow < Igniter::Contract
-  correlate_by :request_id
+### 2. App
 
-  define do
-    input :request_id
+Use this when you want Igniter to be the runtime shape of an application:
 
-    await :crm_data,     event: :crm_received
-    await :billing_data, event: :billing_received
+- app profile
+- host/loader/scheduler seams
+- stack-style project layout
+- app diagnostics and evolution/governance layers
 
-    aggregate :report, with: %i[crm_data billing_data] do |crm_data:, billing_data:|
-      { crm: crm_data, billing: billing_data }
-    end
+Read:
 
-    output :report
-  end
+- [`docs/guide/app.md`](./docs/guide/app.md)
 
-  on_success :report do |value:, **|
-    puts "Report ready: #{value.inspect}"
-  end
-end
+### 3. Cluster
 
-store = Igniter::Runtime::Stores::MemoryStore.new
+Use this when execution stops being single-node:
 
-# Launch — suspends waiting for both events
-execution = LeadWorkflow.start({ request_id: "r1" }, store: store)
-execution.pending?  # => true
+- mesh and gossip
+- capability-based routing
+- replication and distributed coordination
+- resilience and decentralized runtime concerns
 
-# Deliver events from any process or webhook handler
-LeadWorkflow.deliver_event(:crm_received,
-  correlation: { request_id: "r1" },
-  payload: { company: "Acme Corp", tier: "enterprise" },
-  store: store)
+Read:
 
-LeadWorkflow.deliver_event(:billing_received,
-  correlation: { request_id: "r1" },
-  payload: { mrr: 500 },
-  store: store)
-# => prints "Report ready: { crm: ..., billing: ... }"
-```
+- [`docs/guide/cluster.md`](./docs/guide/cluster.md)
 
-See [`examples/distributed_server.rb`](examples/distributed_server.rb) and [`docs/DISTRIBUTED_CONTRACTS_V1.md`](docs/DISTRIBUTED_CONTRACTS_V1.md).
+### 4. SDK
 
-### 10. igniter-server
+Use SDK packs when the kernel needs optional capabilities:
 
-Host contracts as an HTTP service and call them from another graph with the `remote:` DSL:
+- AI
+- channels
+- tools
+- skills
+- data and app-facing capability packs
 
-```ruby
-# --- Service node on port 4568 ---
-require "igniter/server"
+Read:
 
-class ScoringContract < Igniter::Contract
-  define do
-    input :value
-    compute :score, depends_on: :value, call: ->(value:) { value * 1.5 }
-    output :score
-  end
-end
+- [`docs/guide/sdk.md`](./docs/guide/sdk.md)
 
-Igniter::Server.configure { |c| c.port = 4568; c.register "ScoringContract", ScoringContract }
-Igniter::Server.start
+## Suggested Reading Paths
 
-# --- Orchestrator on port 4567 ---
-require "igniter/server"
+If you are new to Igniter:
 
-class PipelineContract < Igniter::Contract
-  define do
-    input :data
-    remote :scored,
-           contract: "ScoringContract",
-           node:     "http://localhost:4568",
-           inputs:   { value: :data }
-    output :scored
-  end
-end
+1. Read [`docs/guide/`](./docs/guide/README.md)
+2. Read [`docs/concepts/`](./docs/concepts/README.md)
+3. Run one or two scripts from [`examples/README.md`](./examples/README.md)
 
-Igniter::Server.configure { |c| c.port = 4567; c.register "PipelineContract", PipelineContract }
-Igniter::Server.start
-```
+If you want to work on Igniter itself:
 
-**CLI:**
+1. Read [`docs/dev/`](./docs/dev/README.md)
+2. Read [`docs/dev/architecture-index.md`](./docs/dev/architecture-index.md)
+3. Then move to the relevant package or layer index
 
-```bash
-# Generate a new application scaffold
-igniter-server new my_app
+If you want the standard app shape:
 
-# Start a server directly
-igniter-server start --port 4568 --require ./contracts.rb
-```
+1. Read [`docs/guide/`](./docs/guide/README.md)
+2. Read [`docs/guide/app.md`](./docs/guide/app.md)
+3. Read [`docs/guide/cli.md`](./docs/guide/cli.md)
+4. Explore [`examples/companion/README.md`](./examples/companion/README.md)
 
-**Rack / Puma (`config.ru`):**
+If you want distributed ideas:
 
-```ruby
-require "igniter/server"
-require_relative "contracts"
-Igniter::Server.configure { |c| c.register "ScoringContract", ScoringContract }
-run Igniter::Server.rack_app
-```
-
-**REST API:**
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/v1/contracts/:name/execute` | Execute a contract synchronously |
-| `POST` | `/v1/contracts/:name/events` | Deliver an event to a distributed contract |
-| `GET`  | `/v1/executions/:id` | Poll execution status |
-| `GET`  | `/v1/health` | Health check with registered contracts list |
-| `GET`  | `/v1/contracts` | List contracts with inputs and outputs |
-
-See [`docs/SERVER_V1.md`](docs/SERVER_V1.md) for the full API reference, deployment patterns, and security notes.
-
-### 11. LLM Integration
-
-Use language models as first-class compute nodes. Supported providers: Ollama (local, zero API cost),
-Anthropic (Claude), OpenAI (and compatible APIs: Groq, Mistral, Azure OpenAI):
-
-```ruby
-require "igniter/integrations/llm"
-
-Igniter::LLM.configure do |c|
-  c.default_provider = :anthropic
-  c.anthropic.api_key = ENV["ANTHROPIC_API_KEY"]
-end
-
-class ClassifyExecutor < Igniter::LLM::Executor
-  provider :anthropic
-  model    "claude-haiku-4-5-20251001"
-  system_prompt "Classify feedback into: bug_report, feature_request, question."
-
-  def call(feedback:)
-    complete("Classify: #{feedback}")
-  end
-end
+1. Read [`docs/guide/`](./docs/guide/README.md)
+2. Read [`docs/guide/cluster.md`](./docs/guide/cluster.md)
+3. Run cluster-oriented scripts from [`examples/README.md`](./examples/README.md)
 
-class DraftResponseExecutor < Igniter::LLM::Executor
-  provider :anthropic
-  model    "claude-haiku-4-5-20251001"
-  system_prompt "You are a customer success agent. Write one professional response sentence."
+If you are iterating on ideas locally:
 
-  def call(feedback:, category:)
-    complete("Feedback: #{feedback}\nCategory: #{category}\nDraft a response.")
-  end
-end
+- keep public learning material in [`examples/`](./examples/README.md)
+- keep local-first experiments in [`playgrounds/`](./playgrounds/README.md)
 
-class FeedbackTriageContract < Igniter::Contract
-  define do
-    input :feedback
+## Documentation Layout
 
-    compute :category, depends_on: :feedback,             with: ClassifyExecutor
-    compute :response, depends_on: %i[feedback category], with: DraftResponseExecutor
+- [`docs/guide/`](./docs/guide/README.md) — user-facing docs: getting started, API, how-tos, configuration
+- [`docs/concepts/`](./docs/concepts/README.md) — durable mental models and patterns
+- [`docs/current/`](./docs/current/README.md) — current-state notes and near-term direction
+- [`docs/dev/`](./docs/dev/README.md) — internal docs: architecture, package boundaries, migration plans, backlog
+- [`packages/*/README.md`](./packages/igniter-core/README.md) — package-local quick reference owned by each gem
+- [`docs/`](./docs/README.md) — top-level docs portal that routes between sections
 
-    output :category
-    output :response
-  end
-end
-```
-
-Multi-step reasoning with conversation history:
-
-```ruby
-class MultiStepExecutor < Igniter::LLM::Executor
-  def call(text:, prior_analysis:)
-    ctx = Context.empty(system: self.class.system_prompt)
-      .append_user("Initial: #{text}")
-      .append_assistant(prior_analysis)
-    chat(context: ctx)
-  end
-end
-```
-
-See [`examples/llm/research_agent.rb`](examples/llm/research_agent.rb), [`examples/llm/tool_use.rb`](examples/llm/tool_use.rb), and [`docs/LLM_V1.md`](docs/LLM_V1.md).
-
-### 12. Igniter::Application
-
-Package contracts, executors, scheduler, and server config into a single coherent entry point:
+If you want to scaffold a new stack quickly:
 
 ```bash
-# Scaffold a new application
-igniter-server new my_app
-cd my_app && bundle install && bin/start
+bin/igniter-stack new my_app
+bin/igniter-stack new my_hub --profile dashboard
+bin/igniter-stack new mesh_lab --profile cluster
+bin/igniter-stack new playgrounds/home-lab --profile playground
 ```
 
-```ruby
-require "igniter/application"
-
-class MyApp < Igniter::Application
-  config_file "application.yml"       # optional YAML base config
-
-  configure do |c|
-    c.port  = ENV.fetch("PORT", 4567).to_i
-    c.store = Igniter::Runtime::Stores::MemoryStore.new
-  end
-
-  executors_path "executors/"         # eager-require all executors
-  contracts_path "contracts/"         # eager-require all contracts
-
-  register "OrderContract", OrderContract
-
-  schedule :cleanup, every: "1h" do
-    puts "[cleanup] #{Time.now.strftime("%H:%M")}"
-  end
-
-  schedule :report, every: "1d", at: "09:00" do
-    DailyReportContract.new.resolve_all(date: Date.today)
-  end
-end
-
-MyApp.start       # blocking built-in HTTP server
-# or
-MyApp.rack_app    # Rack app for Puma / Unicorn
-```
-
-**`application.yml`** — base config loaded before the `configure` block (block always wins):
-
-```yaml
-server:
-  port: 4567
-  host: "0.0.0.0"
-  log_format: json    # text (default) or json
-  drain_timeout: 30
-```
-
-**Scheduler interval formats:** `30` (seconds), `"30s"`, `"5m"`, `"2h"`, `"1d"`, `{ hours: 1, minutes: 30 }`
-
-See [`docs/APPLICATION_V1.md`](docs/APPLICATION_V1.md) for the full reference and companion app example.
-
-### 13. Capability-Based Security
-
-Declare what external resources an executor needs, then deny specific capabilities at the
-policy level — without touching the executors themselves:
-
-```ruby
-require "igniter/capabilities"
-
-class DbLookup < Igniter::Executor
-  capabilities :database
-
-  def call(id:)
-    DB.find(id)
-  end
-end
-
-class PureCalc < Igniter::Executor
-  pure  # shorthand for capabilities(:pure)
-
-  def call(x:, y:) = x + y
-end
-
-# Inspect the graph's surface area before deploying
-MyContract.compiled_graph.required_capabilities
-# => { fetch: [:database], total: [:pure] }
-
-# Enforce policy at boot time
-Igniter::Capabilities.policy = Igniter::Capabilities::Policy.new(denied: [:database])
-
-MyContract.new(id: 1).resolve_all
-# => CapabilityViolationError: Node 'fetch' uses denied capabilities: database
-```
-
-See [`docs/CAPABILITIES_V1.md`](docs/CAPABILITIES_V1.md).
-
-### 14. Temporal Contracts
-
-Make time an explicit input so every execution is fully reproducible:
-
-```ruby
-require "igniter/temporal"
-
-class TaxRateContract < Igniter::Contract
-  include Igniter::Temporal
-
-  define do
-    input :country
-    # `as_of` is injected automatically (default: Time.now)
-
-    temporal_compute :rate, depends_on: :country do |country:, as_of:|
-      HISTORICAL_RATES.dig(country, as_of.year) || 0.0
-    end
-
-    output :rate
-  end
-end
-
-# Current rate
-TaxRateContract.new(country: "UA").result.rate
-# => 0.22
-
-# Reproduce the exact 2024 result
-TaxRateContract.new(country: "UA", as_of: Time.new(2024, 1, 1)).result.rate
-# => 0.20
-```
-
-See [`docs/TEMPORAL_V1.md`](docs/TEMPORAL_V1.md).
-
-### 15. Content-Addressed Computation
-
-`pure` executors are cached by a fingerprint of their logic + inputs. Identical computation
-is never repeated — within an execution, across executions, or across processes:
+## Installation
 
 ```ruby
-require "igniter/extensions/content_addressing"
-
-class TaxCalculator < Igniter::Executor
-  pure
-  fingerprint "tax_calc_v1"   # bump to invalidate the cache when logic changes
-
-  def call(country:, amount:)
-    TAX_RATES[country] * amount
-  end
-end
-
-# First execution — computes and caches
-InvoiceContract.new(country: "UA", amount: 1000).result.tax  # computed
-
-# Second execution — served from cache; TaxCalculator is never called
-InvoiceContract.new(country: "UA", amount: 1000).result.tax  # cache hit
-
-# Distributed cache (Redis) — shared across all nodes
-Igniter::ContentAddressing.cache = RedisContentCache.new(Redis.new)
+gem "igniter"
 ```
 
-See [`docs/CONTENT_ADDRESSING_V1.md`](docs/CONTENT_ADDRESSING_V1.md).
-
-### 16. Incremental Dataflow — O(change) Collection Processing
-
-`mode: :incremental` on a collection node makes the runtime diff the input array on
-every `resolve_all`. Only added/changed items have their child contract re-run;
-unchanged items reuse the cached result; removed items are retracted automatically.
-
-```ruby
-require "igniter/extensions/dataflow"
-
-class SensorPipeline < Igniter::Contract
-  define do
-    input :readings, type: :array
+## Public Entry Points
 
-    collection :processed,
-               with: :readings,
-               each: SensorAnalysis,
-               key:  :sensor_id,
-               mode: :incremental,
-               window: { last: 1000 }   # bounded memory
+| Need | Require |
+|------|---------|
+| Core contracts/runtime | `require "igniter"` |
+| Contract/tool kernel | `require "igniter/core"` |
+| Actor runtime and built-in agents | `require "igniter/agent"` or `require "igniter/agents"` |
+| SDK registry | `require "igniter/sdk"` |
+| App runtime/profile | `require "igniter/app"` |
+| Cluster runtime | `require "igniter/cluster"` |
 
-    output :processed
-  end
-end
+The fuller map lives in [`docs/guide/README.md`](./docs/guide/README.md).
 
-pipeline = SensorPipeline.new(readings: initial_batch)
-pipeline.resolve_all  # all N items run once
+## Repository Landmarks
 
-# Push only the delta — no full-array replacement needed
-pipeline.feed_diff(:readings,
-  add:    [{ sensor_id: "new-1", value: 10 }],
-  update: [{ sensor_id: "tmp-2", value: 90 }],
-  remove: ["hum-1"]
-)
-pipeline.resolve_all  # only 2 child contracts run (new-1 + tmp-2)
+- [`docs/`](./docs/README.md) — structured documentation portal
+- [`docs/guide/`](./docs/guide/README.md) — user-facing docs
+- [`docs/dev/`](./docs/dev/README.md) — contributor-facing docs
+- [`examples/`](./examples/README.md) — public runnable examples
+- [`examples/companion/`](./examples/companion/README.md) — canonical stack-style demo
+- [`playgrounds/`](./playgrounds/README.md) — local-first experiments such as home-lab work
 
-diff = pipeline.collection_diff(:processed)
-diff.processed_count  # => 2
-diff.unchanged.size   # => N - 2
-```
+## Status
 
-See [`docs/DATAFLOW_V1.md`](docs/DATAFLOW_V1.md).
-
-## Examples
-
-| Example | Run | Shows |
-|---------|-----|-------|
-| `basic_pricing.rb` | `ruby examples/basic_pricing.rb` | Basic contract, lazy resolution, input updates |
-| `composition.rb` | `ruby examples/composition.rb` | Nested contracts and composed results |
-| `diagnostics.rb` | `ruby examples/diagnostics.rb` | Diagnostics text and machine-readable output |
-| `async_store.rb` | `ruby examples/async_store.rb` | Pending execution, file-backed store, worker-style resume |
-| `marketing_ergonomics.rb` | `ruby examples/marketing_ergonomics.rb` | `const`, `lookup`, `map`, `guard`, `scope`, `namespace`, `expose`, `on_success`, `explain_plan` |
-| `collection.rb` | `ruby examples/collection.rb` | Fan-out, stable item keys, `CollectionResult` |
-| `collection_partial_failure.rb` | `ruby examples/collection_partial_failure.rb` | `:collect` mode, partial failure summary, collection diagnostics |
-| `ringcentral_routing.rb` | `ruby examples/ringcentral_routing.rb` | `branch`, nested `collection`, `project`, `aggregate`, diagnostics |
-| `order_pipeline.rb` | `ruby examples/order_pipeline.rb` | `guard` + `collection` + `branch` + `export` in one flow |
-| `distributed_server.rb` | `ruby examples/distributed_server.rb` | `await`, `correlate_by`, `start`, `deliver_event`, `on_success` |
-| `server/node1.rb` + `node2.rb` | run both, then curl | Two-node igniter-server with `remote:` DSL |
-| `llm/research_agent.rb` | `ruby examples/llm/research_agent.rb` | Multi-step LLM pipeline with Ollama |
-| `llm/tool_use.rb` | `ruby examples/llm/tool_use.rb` | LLM tool declarations, chained LLM nodes, `Context` |
-| `companion/demo.rb` | `ruby examples/companion/demo.rb` | End-to-end voice AI pipeline using `Igniter::Application` |
-| `dataflow.rb` | `ruby examples/dataflow.rb` | Incremental sensor pipeline: `mode: :incremental`, `feed_diff`, sliding window |
-
-## Design Docs
-
-- [Architecture v2](docs/ARCHITECTURE_V2.md)
-- [Execution Model v2](docs/EXECUTION_MODEL_V2.md)
-- [API Draft v2](docs/API_V2.md)
-- [Patterns](docs/PATTERNS.md)
-- [Branches v1](docs/BRANCHES_V1.md)
-- [Collections v1](docs/COLLECTIONS_V1.md)
-- [Distributed Contracts v1](docs/DISTRIBUTED_CONTRACTS_V1.md)
-- [Store Adapters](docs/STORE_ADAPTERS.md)
-- [igniter-server v1](docs/SERVER_V1.md)
-- [LLM Integration v1](docs/LLM_V1.md)
-- [Application scaffold v1](docs/APPLICATION_V1.md)
-- [Capabilities v1](docs/CAPABILITIES_V1.md)
-- [Temporal Contracts v1](docs/TEMPORAL_V1.md)
-- [Content Addressing v1](docs/CONTENT_ADDRESSING_V1.md)
-- [Incremental Dataflow v1](docs/DATAFLOW_V1.md)
-- [Concepts and Principles](docs/IGNITER_CONCEPTS.md)
-
-## Development
+Igniter is intentionally being shaped as layered infrastructure:
 
-```bash
-rake          # specs + RuboCop
-rake spec     # tests only
-rake rubocop  # lint only
-rake build    # build gem
-```
+- keep `core` small and strict
+- let `app` and `cluster` grow above it
+- move reusable optional capabilities into `sdk`
+- keep user docs in `docs/guide/`
+- keep internal architecture and planning docs in `docs/dev/`
+- keep package-local quick reference next to each package README
 
-Current feature baseline:
-
-- synchronous runtime + parallel thread-pool runner
-- pending / deferred node states with snapshot / restore
-- store-backed resume flow (MemoryStore, FileStore)
-- compile-time graph validation, typed inputs, cycle detection
-- composition, branch, collection, guard, scope / namespace
-- distributed workflows: `await`, `correlate_by`, `start`, `deliver_event`
-- igniter-server: TCP server, Rack adapter, CLI, `remote:` DSL
-- LLM compute nodes: Ollama, Anthropic, OpenAI providers
-- Rails integration: Railtie, ActiveJob, ActionCable, webhook controller mixin
-- `Igniter::Application`: YAML config, autoloading, scheduler, generator (`igniter-server new`)
-- auditing, diagnostics, reactive subscriptions, graph introspection
-- capability-based security: `capabilities`, `pure`, `Policy`, `CapabilityViolationError`
-- temporal contracts: `include Igniter::Temporal`, `temporal_compute`, `as_of` input, historical reproduction
-- content-addressed computation: `pure`, `fingerprint`, universal `ContentKey`, pluggable `ContentCache`
-- incremental dataflow: `mode: :incremental`, `window:`, `feed_diff`, `collection_diff`, `DiffState`, `IncrementalCollectionResult`
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+For the full documentation map, start at [`docs/README.md`](./docs/README.md).