igniter 0.5.1 → 0.5.2

data/docs/guide/cli.md

@@ -0,0 +1,70 @@
+# CLI
+
+This is the shortest guide to the current stack-first CLI surface.
+
+## Main Entry Points
+
+- `bin/start` — start the mounted stack runtime
+- `bin/start --node NAME` — start one local node profile
+- `bin/console` — open the igniter console
+- `bin/console --node NAME` — open console with one node profile selected
+- `bin/console --node NAME --eval '...'` — evaluate one expression and exit
+- `bin/dev` — start all local node profiles with prefixed output
+
+`bin/dev` also writes per-node logs to `var/log/dev/*.log`.
+
+## Scaffold Profiles
+
+`igniter-stack new` currently supports:
+
+- base profile by default
+- `--profile dashboard` for a mounted dashboard app at `/dashboard`
+- `--profile cluster` for a cluster-ready sandbox with node profiles and self-heal demo
+- `--profile playground` for a richer local lab scaffold
+
+Examples:
+
+```bash
+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
+```
+
+## Mental Model
+
+- `stack.rb` is the executable runtime surface
+- positional `app` means “run this one app directly”
+- `--node` means “boot the stack as this node profile”
+- `--console` means “load stack/app/runtime helpers into IRB”
+
+## Console Helpers
+
+Inside `bin/console`, these locals are available:
+
+- `stack`
+- `context`
+- `app`
+- `root_app`
+- `node`
+- `node_profile`
+- `deployment`
+- `runtime`
+- `mounts`
+- `mesh`
+- `stack_settings`
+
+Example:
+
+```bash
+bin/console --node seed --eval 'context.node_name'
+```
+
+## Built-In Help
+
+The runtime also exposes help directly:
+
+```bash
+bundle exec ruby stack.rb --help
+bundle exec ruby stack.rb --console --help
+```

data/docs/guide/cluster.md

@@ -0,0 +1,55 @@
+# Cluster
+
+Use this section when execution is no longer single-node and the network itself becomes part of the runtime.
+
+## Cluster Means
+
+- mesh membership and gossip
+- capability-based routing across peers
+- replication and distributed coordination
+- resilience, plasticity, and decentralized runtime behavior
+- cluster diagnostics and routing explainability
+
+The cluster layer should stay above `Embed` and `Application`. It is not the
+place to redefine the kernel.
+
+## Current First Reads
+
+- [Guide](../guide/README.md)
+- [Guide: How-Tos](../guide/how-tos.md)
+- [Dev: Cluster Target Plan](../dev/cluster-target-plan.md)
+
+## Supporting Reference
+
+- [Guide: Distributed Workflows](../guide/distributed-workflows.md)
+
+## Useful Supporting Docs
+
+- [Guide: Core Runtime Features](../guide/core-runtime-features.md)
+
+## Examples
+
+- [Examples index](../../examples/README.md)
+- cluster-oriented examples such as `cluster/incidents`,
+  `cluster/incident_workflow`, `cluster/mesh_diagnostics`,
+  `cluster/remediation`, and `cluster/routing`
+- [Playgrounds](../../playgrounds/README.md) for local-first cluster and home-lab experiments
+
+## Cluster Reading Heuristic
+
+- If the topic is about contracts or execution semantics without networking,
+  it probably belongs back in [Core](./core.md).
+- If the topic is about app boot/profile without network coordination, it
+  probably belongs in [App](./app.md).
+
+## Direction
+
+Current design direction:
+
+- `Cluster` is being reset as a contracts-native distributed runtime layer
+- it should sit above `Embed` and `Application`, not redefine either of them
+- new design work should follow the
+  [Cluster Target Plan](../dev/cluster-target-plan.md)
+
+Older cluster research and legacy notes are private working material under
+`playgrounds/docs/`, not public onboarding.

data/docs/guide/configuration.md

@@ -0,0 +1,31 @@
+# Configuration
+
+Use this index when the question is operational: boot shape, deployment, stack
+layout, or persistence.
+
+## Current Starting Points
+
+- [CLI](./cli.md)
+- [Application Capsules](./application-capsules.md)
+- [Deployment Modes](./deployment-modes.md)
+- [App](./app.md)
+
+## Runtime And Deployment Reference
+
+- [Deployment Modes](./deployment-modes.md)
+- [Credentials](./credentials.md)
+- [Store Adapters](./store-adapters.md)
+- [Application Capsules](./application-capsules.md)
+
+## Current Heuristic
+
+- Start embedded with `require "igniter"` when the host app already exists.
+- Move to `igniter-application` when Igniter becomes the runtime shape.
+- Move to `igniter-cluster` only when distribution is a real execution concern.
+
+## Project Shapes
+
+- [Examples](../../examples/README.md)
+- [Application Showcase Portfolio](./application-showcase-portfolio.md)
+- [Interactive App Structure](./interactive-app-structure.md)
+- [Playgrounds](../../playgrounds/README.md)

data/docs/guide/contract-class-dsl.md

@@ -0,0 +1,154 @@
+# Contract Class DSL
+
+Igniter contracts have two equal authoring forms:
+
+- block compilation for low-level embedding and generated graphs
+- class DSL for human-edited application code
+
+For a runnable path across contracts, examples, application showcases, and Lang,
+start with [Getting Started](./getting-started.md).
+
+Use the class form when a Rails/service/job author needs to read the contract as
+business logic.
+
+```ruby
+class PriceContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    input :country, type: :string
+
+    compute :vat_rate, depends_on: [:country] do |country:|
+      country == "UA" ? 0.2 : 0.0
+    end
+
+    compute :gross_total, depends_on: %i[order_total vat_rate] do |order_total:, vat_rate:|
+      order_total * (1 + vat_rate)
+    end
+
+    output :gross_total
+  end
+end
+
+contract = PriceContract.new(order_total: 100, country: "UA")
+contract.result.gross_total
+contract.update_inputs(order_total: 150)
+contract.output(:gross_total)
+```
+
+## Why This Form Exists
+
+The block form is still the smallest kernel surface:
+
+```ruby
+compiled = Igniter::Contracts.compile do
+  input :amount
+  output :amount
+end
+```
+
+The class form adds the shape app code usually wants:
+
+- one contract per file
+- a compact `define do ... end` body
+- result readers such as `contract.result.gross_total`
+- `update_inputs` for repeated local runs
+- a stable class name that host layers can register, cache, reload, and call
+
+This is not a separate runtime. `Igniter::Contract` compiles and executes
+through `igniter-contracts`.
+
+## Callable Steps
+
+Use blocks for local logic and `call:` for existing service objects.
+
+```ruby
+class GrossTotal
+  def self.call(order_total:, vat_rate:)
+    order_total * (1 + vat_rate)
+  end
+end
+
+class PriceContract < Igniter::Contract
+  define do
+    input :order_total
+    input :vat_rate
+    compute :gross_total, depends_on: %i[order_total vat_rate], call: GrossTotal
+    output :gross_total
+  end
+end
+```
+
+Callable objects receive keyword arguments named after `depends_on`.
+
+## Result Shape
+
+The minimum reader surface is intentionally small:
+
+```ruby
+contract = PriceContract.new(order_total: 100, vat_rate: 0.2)
+
+contract.success?
+contract.failure?
+contract.outputs
+contract.output(:gross_total)
+contract.result.gross_total
+contract.to_h
+```
+
+Unknown result readers raise a clear `KeyError`.
+
+## Embed Hosts
+
+`igniter-embed` consumes contract classes without redefining the DSL:
+
+```ruby
+contracts = Igniter::Embed.configure(:shop) do |config|
+  config.cache = true
+  config.root "app/contracts"
+  config.contract PriceContract, as: :price_quote
+end
+
+result = contracts.call(:price_quote, order_total: 100, country: "UA")
+result.output(:gross_total)
+```
+
+Named contract classes can also be registered directly. The inferred name uses
+the last class segment, removes a trailing `Contract`, and snake-cases it:
+
+```ruby
+contracts.register(Billing::PriceContract)
+contracts.call(:price, order_total: 100, country: "UA")
+```
+
+The host layer owns naming, caching, reload hooks, and failure envelopes. The
+contract class owns the business graph.
+
+`config.root` identifies the host-local contract directory. It does not load
+files by itself. Automatic discovery is opt-in:
+
+```ruby
+contracts = Igniter::Embed.configure(:shop) do |config|
+  config.root "app/contracts"
+  config.discover!
+end
+```
+
+Discovery is useful for small scripts and experiments. For application boot,
+prefer explicit `config.contract SomeContract, as: :name` until you want a
+convention-driven loader.
+
+Discovery only registers named contract classes. Anonymous classes are ignored,
+explicit registrations win over discovered contracts with the same name, and
+duplicate discovered names raise a discovery error so hosts do not silently pick
+the wrong contract.
+
+## Design Pressure
+
+The class DSL removes most container ceremony from app-local contracts. The next
+ergonomics target is reducing repeated fail-fast and host registration boilerplate
+without hiding the business graph.
+
+## Related
+
+- [Getting Started](./getting-started.md)
+- [Igniter Lang Foundation](./igniter-lang-foundation.md)

data/docs/guide/core-runtime-features.md

@@ -0,0 +1,34 @@
+# Core Runtime Features
+
+Use this page for features that still belong near the embedded contracts
+kernel.
+
+## Current Shape
+
+- contract DSL and class DSL
+- graph compilation and validation
+- local execution
+- diagnostics and structured reports
+- explicit optional packs from `igniter-extensions`
+
+Optional features should be installed through explicit packs. Avoid hidden
+global activation and old `igniter/core/*` entrypoints in new public examples.
+
+## Heuristic
+
+Keep a feature near the embedded kernel when it is about computation semantics
+or local execution behavior.
+
+Move it upward when it needs:
+
+- app boot/profile lifecycle
+- web rendering or browser interaction
+- framework integration
+- distributed routing or placement
+
+## Reading Path
+
+- [Core](./core.md)
+- [API And Runtime](./api-and-runtime.md)
+- [Module System](../dev/module-system.md)
+- [`packages/igniter-extensions/README.md`](../../packages/igniter-extensions/README.md)

data/docs/guide/core.md

@@ -0,0 +1,43 @@
+# Core
+
+This document currently describes the embedded/kernel role. In the target
+architecture, the clearer name for that role is `Embed`.
+
+Use this section when the thing you care about should still make sense in embedded mode with `require "igniter"`.
+
+## Core Means
+
+- contract DSL
+- graph model and compilation
+- runtime execution and invalidation
+- diagnostics, introspection, provenance-friendly observation
+- dataflow semantics such as branches, collections, async/deferred execution
+
+If a capability stops making sense without hosting, networking, or optional packs, it probably does not belong in core.
+
+## Current First Reads
+
+- [Guide](../guide/README.md)
+- [Guide: API And Runtime](../guide/api-and-runtime.md)
+- [Guide: Core Runtime Features](../guide/core-runtime-features.md)
+- [Dev: Embed Target Plan](../dev/embed-target-plan.md)
+- [Igniter Concepts](../concepts/igniter.md)
+- [Dev: Architecture](../dev/architecture.md)
+
+## Supporting Reference
+
+- [Guide: Core Runtime Features](../guide/core-runtime-features.md)
+
+## When To Leave Core
+
+- Move to [App](./app.md) when you need app runtime/profile concerns.
+- Move to [Cluster](./cluster.md) when you need networking, mesh, routing,
+  replication, or resilience.
+- Move to [`igniter-extensions`](../../packages/igniter-extensions/README.md)
+  when you need optional packs.
+
+Current design direction:
+
+- treat this layer as the canonical embedded/contracts-first operating mode
+- do not let it absorb application or cluster concerns by default
+- for the target model, follow the [Embed Target Plan](../dev/embed-target-plan.md)

data/docs/guide/credentials.md

@@ -0,0 +1,51 @@
+# Credentials
+
+Use credentials when an Igniter application needs secrets such as API keys but
+must still boot cleanly without them.
+
+## Current Shape
+
+Credentials live in `igniter-application` as app runtime configuration. The
+first supported source is an environment variable:
+
+```ruby
+environment = Igniter::Application.build_kernel
+                                  .credential(
+                                    :openai_api_key,
+                                    env: "OPENAI_API_KEY",
+                                    required: false
+                                  )
+                                  .then { |kernel| Igniter::Application::Environment.new(profile: kernel.finalize) }
+```
+
+Application code can ask whether live mode is available:
+
+```ruby
+if environment.credentials.configured?(:openai_api_key)
+  api_key = environment.credentials.fetch(:openai_api_key)
+else
+  # show setup state or run offline mode
+end
+```
+
+## Rules
+
+- Missing optional credentials should produce setup state, not a crash.
+- Missing required credentials raise `MissingCredentialError` when fetched.
+- `profile.to_h`, manifests, snapshots, reports, and logs must not include
+  secret values.
+- Smoke tests should stay offline and deterministic by default.
+- Live provider calls should be opt-in through configured credentials.
+
+## Ready-To-Go App Pattern
+
+For live LLM applications:
+
+- declare `:openai_api_key` against `OPENAI_API_KEY`
+- boot without the key
+- show a visible setup message when the key is missing
+- switch to live mode when the key exists
+- keep offline smoke paths independent from the live provider
+
+This keeps examples runnable for everyone while making real API usage one
+configuration step away.

data/docs/guide/deployment-modes.md

@@ -0,0 +1,63 @@
+# Deployment Modes
+
+Igniter has three current operating modes. The same contract can often move
+between them while the surrounding runtime grows.
+
+## 1. Embedded
+
+Use this when Igniter runs inside an existing host such as Rails, a job, a CLI,
+or a service.
+
+```ruby
+require "igniter"
+```
+
+Add optional packs explicitly through package entrypoints such as
+`igniter-extensions` or host integration through `igniter-embed`.
+
+Choose embedded mode when contracts are called directly and you do not need app
+hosting, web mounting, or distributed execution.
+
+## 2. Application
+
+Use this when Igniter becomes the local runtime shape of an app.
+
+Current package:
+
+```ruby
+require "igniter-application"
+```
+
+Use this mode for app profiles, providers, services, capsules, local lifecycle,
+transfer review, activation review, and app-owned session state.
+
+## 3. Cluster
+
+Use this when the network becomes part of execution.
+
+Current package:
+
+```ruby
+require "igniter-cluster"
+```
+
+Use this mode for capability routing, peer topology, placement, ownership,
+health, failover, remediation, and distributed diagnostics.
+
+## Web Is A Surface
+
+`igniter-web` can be used with application mode, but web rendering is not the
+same thing as app hosting. Keep screens, routes, components, and browser
+surfaces web-owned.
+
+## Pre-v1 Note
+
+Older entrypoint language belongs to private historical context unless a package
+README explicitly documents it as current.
+
+## See Also
+
+- [Getting Started](./getting-started.md)
+- [Configuration](./configuration.md)
+- [App](./app.md)
+- [Cluster](./cluster.md)

data/docs/guide/distributed-workflows.md

@@ -0,0 +1,21 @@
+# Distributed Workflows
+
+Use this page when a contract is no longer just in-process computation and must
+wait for or react to signals that may arrive later or on another node.
+
+## Current Mental Model
+
+Distributed workflow concerns belong above the embedded kernel:
+
+- the contract graph stays explicit
+- correlation keys matter more than process memory
+- waiting on external signals should be visible in workflow state
+- transport stays outside the workflow model
+
+## Current Reading Path
+
+- [Cluster](./cluster.md)
+- [Guide: Deployment Modes](./deployment-modes.md)
+
+Historical distributed-workflow references are private working material under
+`playgrounds/docs/`.

data/docs/guide/getting-started.md

@@ -0,0 +1,49 @@
+# Getting Started
+
+This is the shortest user-facing path into Igniter.
+
+## 1. Start With The Core Idea
+
+Read:
+
+- [Top-level README](../../README.md)
+- [Igniter Concepts](../concepts/igniter.md)
+- [Core](./core.md)
+
+## 2. Run Something Real
+
+Use:
+
+- [Examples](../../examples/README.md)
+- [Application Showcase Portfolio](./application-showcase-portfolio.md)
+- [Interactive App Structure](./interactive-app-structure.md)
+
+## 3. Pick The Runtime Shape
+
+- Stay in [Core](./core.md) if you only need embedded contracts and execution.
+- Move to [App](./app.md) if Igniter becomes the runtime of an app.
+- Move to [Cluster](./cluster.md) if execution becomes distributed.
+- Add [Extensions](../../packages/igniter-extensions/README.md) only when
+  optional capabilities are needed.
+
+Current architecture note:
+
+- Igniter is pre-v1 and does not promise backward compatibility yet
+- `Core` here really means the embedded/contracts-first operating mode
+- `App` builds on top of that embedded mode
+- `Cluster` builds on top of embedded/application runtime
+
+## 4. Scaffold When You Want The Standard Shape
+
+Read:
+
+- [CLI](./cli.md)
+- [Application Capsules](./application-capsules.md)
+
+Then try:
+
+```bash
+bin/igniter-stack new my_app
+bin/igniter-stack new my_hub --profile dashboard
+bin/igniter-stack new mesh_lab --profile cluster
+```

data/docs/guide/how-tos.md

@@ -0,0 +1,33 @@
+# How-Tos
+
+Use this index for task-oriented documentation rather than architecture-first
+reading.
+
+## Build An App
+
+- [App](./app.md)
+- [CLI](./cli.md)
+- [Application Showcase Portfolio](./application-showcase-portfolio.md)
+- [Interactive App Structure](./interactive-app-structure.md)
+
+## Build A Dashboard Or Human UI
+
+- [Application Showcase Portfolio](./application-showcase-portfolio.md)
+- [Interactive App Structure](./interactive-app-structure.md)
+- [`packages/igniter-web/README.md`](../../packages/igniter-web/README.md)
+
+## Add Rails Integration
+
+- [`packages/igniter-embed/README.md`](../../packages/igniter-embed/README.md)
+- [App](./app.md)
+- [Integrations](./integrations.md)
+
+## Move To Distributed Execution
+
+- [Cluster](./cluster.md)
+- [Distributed Workflows](./distributed-workflows.md)
+
+## Add Optional Capability Packs
+
+- [AI And Tool Surfaces](./ai-and-tools.md)
+- [`packages/igniter-extensions/README.md`](../../packages/igniter-extensions/README.md)