docs(site): publish the volition, planning, agency and research chapters

docs/site/build.py

@@ -40,9 +40,13 @@ CHAPTERS = [
     ("graph", "Relationship graph", "Entities, evidenced edges, merges and the canvas explorer."),
     ("llm-providers", "Language models", "Roles, providers (OpenAI-compatible, Anthropic, Ollama, Amazon Bedrock), per-mind routing, budgets, recorded calls, replay and versioned prompts."),
     ("capabilities", "Capabilities and policy", "The only path to action: ALLOW / ASK / DENY, approvals, locked capabilities and tool output as data."),
+    ("volition", "Volition", "Wants, intentions and commitments as distinct recorded states: generation, conflicts, formation, reconsideration and values."),
+    ("planning", "Planning and execution", "Plans as validated graphs of typed steps, observe-act-verify, replanning, capability negotiation and bounded host operations."),
+    ("agency", "Agency and why", "Authority outside cognition, the causal chain from want to outcome, attribution and forensic explanations."),
     ("integrations", "Integrations", "Research folder, git mirrors, Prometheus and signed webhooks as provenance-tagged observations."),
     ("dreaming", "Dreaming", "The opt-in idle mode: replay, association and speculative hypotheses that can never act."),
     ("snapshots-replay", "Snapshots, forks, replay and experiments", "Capturing state, branching minds, re-running cognition under a recorded runtime identity, and comparing forks that differ in one thing, including the model."),
+    ("cognitive-research", "Cognitive research", "Operational definitions, ablations, introspection accuracy, calibration, agency metrics and the research dashboard, with no claim of consciousness."),
     ("ui-tour", "Interface tour", "Every screen of the web interface, what it shows and what an operator does there."),
     ("api", "HTTP API", "Authentication, roles, the error envelope, streaming and every route."),
     ("cli", "Command line", "What an operator can do from a terminal: every command, with examples."),
@@ -210,7 +214,7 @@ LINK_MAP = {
     "docs/conversation.md": "conversation", "docs/motivation.md": "motivation", "docs/predictions.md": "predictions", "docs/graph.md": "graph",
     "docs/llm-providers.md": "llm-providers", "docs/capabilities.md": "capabilities", "docs/integrations.md": "integrations",
     "docs/dreaming.md": "dreaming", "docs/snapshots-replay.md": "snapshots-replay", "docs/performance.md": "development",
-    "docs/RELEASE_NOTES.md": "development", "docs/privacy.md": "privacy", "docs/epistemics.md": "epistemics", "docs/openapi.json": "api", "docs/adr": "decisions",
+    "docs/RELEASE_NOTES.md": "development", "docs/privacy.md": "privacy", "docs/epistemics.md": "epistemics", "docs/volition.md": "volition", "docs/planning.md": "planning", "docs/agency.md": "agency", "docs/cognitive-research.md": "cognitive-research", "docs/openapi.json": "api", "docs/adr": "decisions",
 }
 
 

docs/site/pages/agency.md

@@ -0,0 +1,7 @@
+Agency in Noema is an operational term: the recorded chain from want to intention to plan to action to observation, and the measured relations along it. The rule underneath it is that a mind may want, intend, commit and plan, but none of that is authority; authority is decided outside cognition by policy rows and named people.
+
+## "Why did this happen?"
+
+Every execution, approval, capability request, intention, plan step and event can be explained forensically from recorded state: the causal chain back through the plan, the intention and its source wants, the commitments consulted, the beliefs relied on as they stood at the time, and the policy decision. Outcomes are attributed conservatively as caused, followed, independent or unknown, and the interface shows the chain on a "why" page.
+
+{{include docs/agency.md}}

docs/site/pages/capabilities.md

@@ -2,18 +2,7 @@ The capability layer is the only way a mind can affect anything outside its own
 
 ## Capabilities
 
-A capability is registered in Go code with a name, description, risk class (low, medium, high, critical), target kind (url, path, host, service, repository, address or none), typed parameters with limits, a default effect and an executor. The built-in set is:
-
-| Capability | Risk | Default | What it does |
-|---|---|---|---|
-| `noema.note` | low | ALLOW | leaves a note for the operator in the mind's own history |
-| `http.fetch` | medium | ASK | fetches a public URL read-only through the hardened HTTP client, bounded in size |
-| `read_metrics` | low | ALLOW | evaluates a PromQL expression against a Prometheus integration connected to the mind |
-| `repository.read` | medium | ASK | reads one file from a git integration connected to the mind |
-| `internet_search` | medium | ASK | stub until a search integration exists; fails closed |
-| `send_email` | high | ASK | stub until a mail integration exists; fails closed |
-| `sudo_shell` | critical | DENY, locked | exists so it can be named; never executes |
-| `delete_database` | critical | DENY, locked | exists so it can be named; never executes |
+A capability is registered in Go code with a name, description, access (read or write), side effects, idempotency, timeout, resource estimate, risk class, policy target derived from its parameters, output trust, typed parameters with limits, a default effect and an executor. The built-in set, including the bounded host and browser capabilities added in 0.3, is tabulated in the reference below.
 
 Nothing at runtime can add a capability, so a mind cannot invent a tool by describing one, and a prompt that names a non-existent capability produces a denied request and nothing else.
 

docs/site/pages/cognitive-research.md

@@ -0,0 +1,5 @@
+Noema makes theories about cognition testable against a running architecture. Attention, global broadcast, self-representation, metacognition, volition and continuity are explicit state, so they can be ablated or overridden in forks and measured, instead of asking a language model whether it feels anything.
+
+> **Noema does not claim that any operational metric establishes phenomenal consciousness or sentience.** The framework measures functional properties of the architecture, and no result should be reported as if it showed more.
+
+{{include docs/cognitive-research.md}}

docs/site/pages/planning.md

@@ -0,0 +1,10 @@
+Plans turn intentions into explicit, revisable work: a directed acyclic graph of typed steps with assumptions, completion criteria, abort conditions, resource estimates and a budget. A language model may propose a decomposition; Go validates it, owns the state machine and invokes every capability through the single capability path. Plans survive restarts, are replanned as new revisions that keep their history, and treat an operator's attention as a scarce resource.
+
+## Guarantees
+
+- **Validated before use.** Unregistered or locked capabilities, cycles, missing dependencies and budget overruns are refused; fields in a proposal claiming approval are ignored.
+- **Observe, act, verify.** A write step can carry a precondition and an expectation; the expectation is resolved by a later read-only observation, never assumed.
+- **Resumable.** Steps are claimed with leases and saved conditionally, so a restart or a second executor cannot run a step twice or move it backwards.
+- **Bounded host access.** Service, log and host capabilities run a fixed allow-list of commands with validated arguments and scrubbed output.
+
+{{include docs/planning.md}}

docs/site/pages/volition.md

@@ -0,0 +1,14 @@
+Version 0.3 gives a mind explicit volition. Wanting, intending, committing and acting are separate computational states, each stored as rows with provenance, each with different consequences, and none of them a grant of authority. A want can persist unacted on; an intention can wait for an operator; a commitment can make an action harder but never easier.
+
+## Why it exists
+
+A reply such as "I wanted to restart the service, but I have committed not to change production without approval, so I asked instead" should correspond to records an operator can open. Without distinct states, a runtime can only report what a language model says it meant. With them, every decision to form, not form, reconsider, suspend or abandon an intention is an entry in an append-only ledger, and the mind may only say "I did X because I wanted Y" when the records link X to Y.
+
+## Guarantees
+
+- **Deterministic.** Want generation, conflict resolution, intention formation and reconsideration are Go rules with named thresholds; a language model only proposes.
+- **Non-formation is recorded.** When a strong want does not become an intention, the reason is stored.
+- **Commitments only tighten.** A "refrain unless approved" commitment turns ALLOW into ASK, and scoped grants do not satisfy it.
+- **No self-preservation drive.** No want, value or commitment can target the mind's own lifecycle or authority, and tests prove it.
+
+{{include docs/volition.md}}