aiwg 2026.9.0 → 2026.9.2

package/README.md

@@ -1,10 +1,10 @@
 <div align="center">
 
-<a href="https://aiwg.io"><img src="https://aiwg.io/assets/badges/aiwg-hero-dark.png" alt="AIWG — multi-agent AI framework · one source of truth · 10 platforms" width="680"></a>
+<a href="https://aiwg.io"><img src="https://aiwg.io/assets/badges/aiwg-hero-dark.png" alt="AIWG — multi-agent AI framework · one source of truth · 12 provider integrations" width="680"></a>
 
 # AIWG
 
-**Multi-agent AI framework for Claude Code, Copilot, Cursor, Warp, and 6 more platforms**
+**Multi-agent AI framework for 12 provider integrations, including Claude Code, Codex, Copilot, Cursor, Pi, and Warp**
 
 200+ agents, 109+ CLI commands, 400+ deployable agent/skill/command/rule artifacts, 8 core frameworks, 32 addons, and a 40-plugin Claude Code marketplace. SDLC workflows, digital forensics, research management, marketing operations, media curation, ops infrastructure, knowledge base, and fine-tuning dataset curation — all deployable with one command.
 
@@ -85,7 +85,8 @@ Agents and stewards setting up AIWG end-to-end should use the
 [![GitHub Stars](https://img.shields.io/github/stars/jmagly/aiwg?style=flat-square)](https://github.com/jmagly/aiwg/stargazers)
 [![Node Version](https://img.shields.io/badge/node-%E2%89%A520.0.0-brightgreen?style=flat-square&logo=node.js)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
-[![10 Platforms](https://img.shields.io/badge/Platforms-10-purple?style=flat-square)](#-platform-support)
+[![12 Providers](https://img.shields.io/badge/Providers-12-purple?style=flat-square)](#-platform-support)
+[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/docs-aiwg-io)
 
 [![Built With AIWG](https://aiwg.io/assets/badges/built-with-aiwg-dark.png)](https://aiwg.io/badges)
 
@@ -163,7 +164,7 @@ You can also invoke AIWG without adjusting `PATH` by using `npx aiwg <command>`.
 
 ## What AIWG Is
 
-AIWG is a deployment tool and support utility for AI context. At its core, `aiwg use` copies markdown and YAML source files into the specific paths each AI platform looks in — `.claude/agents/`, `.agents/skills/`, `.cursor/rules/`, `.github/prompts/`, and six more — so one source of truth works across 10 platforms.
+AIWG is a deployment tool and support utility for AI context. At its core, `aiwg use` copies markdown and YAML source files into the paths each provider reads, so one source of truth works across 12 named provider integrations. A thirteenth `generic` adapter emits portable files for unrecognized or custom harnesses and is not counted as a named integration.
 
 Around that core, AIWG ships agent-facing utilities for things the base platforms do not handle on their own: persistent artifact memory (`.aiwg/`), background orchestration, autonomous loops, artifact indexing, cost telemetry, health diagnostics, and more. These are tools the agent calls when you ask for something AIWG-shaped — you stay in chat. Most are opt-in. The deployment layer works standalone as plain text files the platform reads natively.
 
@@ -542,7 +543,7 @@ The orchestration pattern: **Primary Author → Parallel Reviewers → Synthesiz
 - **128 workflow skills** — natural language triggers for regression testing, forensics, voice profiles, quality gates, and CI/CD integration
 - **35 enforcement rules** — anti-laziness detection, token security, citation integrity, executable feedback, failure mitigation across 6 LLM archetypes
 - **334 artifact templates** — progressive disclosure templates for requirements, architecture, testing, security, deployment, and more
-- **Multi-platform support** — deploy to Claude Code, Copilot, Cursor, Warp, Factory AI, OpenCode, Codex, Devin Desktop, OpenClaw, Hermes, and OpenHuman
+- **Multi-provider support** — deploy to Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Factory AI, Hermes, OpenCode, OpenClaw, OpenHuman, Pi Coding Agent, Warp Terminal, and Devin Desktop
 - **8 core frameworks + training marketplace package** — SDLC, Digital Forensics, Marketing Operations, Research Management, Media Curation, Ops Infrastructure, Knowledge Base, Security Engineering, plus [`aiwg-training`](https://github.com/jmagly/aiwg-training) for fine-tuning dataset curation (corpus-to-dataset pipeline with DPO/KTO/ORPO/SimPO export)
 - **32 addons** — compound memory, line memory, llm-wiki (Obsidian-native knowledge base), RLM recursive decomposition, fleet operations, browser control, testing quality, and more
 - **40 Claude Code plugins** — the complete framework and addon catalog is installable independently from the AIWG marketplace
@@ -1383,7 +1384,7 @@ See [Messaging Guide](docs/messaging-guide.md) for setup and configuration.
 
 ## Platform Support
 
-All 8 platforms receive agents, commands, skills, and rules. Deployment adapts to each platform's conventions automatically.
+AIWG supports 12 named provider integrations. Artifact support varies by provider and is adapted to each provider's native or compatibility surfaces.
 
 | Platform | Status | Agents | Commands | Skills | Rules | Deploy Command |
 |----------|--------|--------|----------|--------|-------|---------------|
@@ -1395,6 +1396,10 @@ All 8 platforms receive agents, commands, skills, and rules. Deployment adapts t
 | **OpenCode** | Tested | `.opencode/agent/` | `.opencode/commands/` | `.opencode/skill/` | `.opencode/rule/` | `--provider opencode` |
 | **OpenAI/Codex** | Tested | `.codex/agents/` | `~/.codex/prompts/` | `.agents/skills/` | `.codex/rules/` | `--provider codex` |
 | **Devin Desktop** | Tested compatibility adapter | AGENTS.md | `.windsurf/workflows/` | `.windsurf/skills/` | `.windsurf/rules/` | `--provider devin` |
+| **Hermes** | Experimental | — | — | `~/.hermes/skills/.aiwg/` | — | `--provider hermes` |
+| **OpenClaw** | Tested | `~/.openclaw/agents/` | `~/.openclaw/commands/` | `~/.openclaw/.aiwg/skills/` | `~/.openclaw/rules/` | `--provider openclaw` |
+| **OpenHuman** | Experimental | — | — | `~/.openhuman/.aiwg/skills/` | `~/.openhuman/.aiwg/rules/` | `--provider openhuman` |
+| **Pi Coding Agent** | Experimental | `.agents/skills/` | `.pi/prompts/` | `.agents/skills/` | `AGENTS.md` | `--provider pi` |
 
 The legacy `--provider windsurf` selector remains supported and writes the
 same `.windsurf/` compatibility paths, but new commands should use `devin`.
@@ -1474,7 +1479,7 @@ aiwg sdlc-accelerate --from-codebase .
 
 ### Extension System
 
-AIWG uses a unified extension system with 10 extension types, all deployable across 8 platforms:
+AIWG uses a unified extension system with 10 extension types, projected onto the supported artifact surfaces of 12 named provider integrations:
 
 | Type | Count | Description |
 |------|-------|-------------|
@@ -1852,7 +1857,7 @@ Full research background, citations, and methodology: [docs/research/](docs/rese
 
 ### For Engineering Teams
 
-**Standardize how your team works with AI across 8 platforms.** Whether your team uses Claude Code, Copilot, Cursor, or Warp, everyone gets the same agents, rules, and workflows. The 35 enforcement rules prevent common AI mistakes: deleting tests to make them pass, fabricating citations, hard-coding tokens, or silently dropping features. Human-in-the-loop gates at phase transitions ensure no AI output reaches production without human review.
+**Standardize how your team works with AI across 12 provider integrations.** Whether your team uses Claude Code, Codex, Copilot, Cursor, Pi, or Warp, everyone can receive the same source workflows adapted to the provider's supported surfaces. The 35 enforcement rules prevent common AI mistakes: deleting tests to make them pass, fabricating citations, hard-coding tokens, or silently dropping features. Human-in-the-loop gates at phase transitions ensure no AI output reaches production without human review.
 
 ### For Platform Engineers
 

package/agentic/code/addons/aiwg-utils/docs/overview.md

@@ -8,7 +8,7 @@ Beyond the rules, aiwg-utils also provides:
 
 - **5 agents**: `context-regenerator`, `aiwg-developer`, `consortium-coordinator`, `self-debug`, `aiwg-steward`
 - **9 skills**: `project-awareness`, `schedule`, `soul-create`, `soul-validate`, `soul-enhance`, `soul-apply`, `soul-blend`, `aiwg-sync`, `aiwg-guide`
-- **Platform regeneration commands**: `aiwg-regenerate-claude`, `aiwg-regenerate-warp`, `aiwg-regenerate-factory`, and equivalents for all 9 providers
+- **Provider regeneration commands**: provider-native `aiwg-regenerate` prompts or skills across all 12 named integrations, adapted to each provider's command surface
 - **Workspace commands**: `workspace-realign`, `workspace-prune-working`, `workspace-reset`
 - **@-mention tooling**: `mention-wire`, `mention-validate`, `mention-report`, `mention-lint`
 - **Hook management**: `hook-enable`, `hook-disable`, `hook-status`, `hook-regenerate`
@@ -59,7 +59,7 @@ Apply when: Telegram/group-chat bots, multi-bot rooms, direct-message business b
 
 #### native-ux-tools
 
-Use platform-native interaction tools (e.g., Claude Code's AskUserQuestion) for interactive questions rather than plain text. One question per interaction turn. Includes a platform capability matrix for all 8 supported providers; falls back to formatted markdown if native tools are unavailable.
+Use provider-native interaction tools (e.g., Claude Code's AskUserQuestion) for interactive questions rather than plain text. One question per interaction turn. The capability matrix covers all 12 named provider integrations and falls back to formatted markdown if native tools are unavailable.
 
 Apply when: interactive commands (`--interactive` flag), decision gates, intake wizards.
 

package/agentic/code/addons/aiwg-utils/skills/aiwg-language-map/SKILL.md

@@ -34,6 +34,50 @@ Each section opens with an explicit `aiwg discover "<phrase>"` example. Table ro
 
 ## Addon capability domains
 
+### Dataset intelligence, indexing & provenance
+
+When a user points AIWG at files, an API, a corpus, or another dataset and asks
+for search, indexing, traceability, provenance, lineage, synchronization, or
+safe retirement—even when they do not know those terms.
+
+Example: `aiwg discover "make this searchable"`. Phrases below pass straight to
+`aiwg discover`.
+
+| Need | Phrase | Bundle |
+|---|---|---|
+| Start from only a source and outcome | `use this data` | dataset-intelligence |
+| Recommend custom indexing safely | `make this searchable` | dataset-intelligence |
+| Add evidence-bearing traceability | `trace this dataset` | dataset-intelligence |
+| Explain record or field lineage | `where did this record come from` | dataset-intelligence |
+| Verify freshness and provenance | `verify this dataset` | dataset-intelligence |
+| Resume an incremental source | `sync this source` | dataset-intelligence |
+| Retire data and derived artifacts safely | `retire this dataset` | dataset-intelligence |
+
+The same governed intake and handoff envelopes serve SDLC, research,
+knowledge-base, media, marketing, ops, and project-local bundles. All execution
+delegates to `aiwg dataset`; the addon does not create a shadow runtime.
+
+### Schemas & data contracts
+
+When the user describes a record, configuration file, event, API payload,
+message, import/export, or other structured data—even when they do not know to
+ask for a schema.
+
+Example: `aiwg discover "define data shape"`. Phrases below pass straight to
+`aiwg discover`.
+
+| Need | Phrase | Bundle |
+|---|---|---|
+| Decide whether structured data needs a contract | `define data shape` | schema-governance |
+| Explain schemas and continue examples-first | `why do I need a schema` | schema-governance |
+| Author and register a canonical schema | `create a schema` | schema-governance |
+| Evolve an existing contract safely | `change an existing schema` | schema-governance |
+| Review correctness and readiness | `review a data contract` | schema-governance |
+
+The SDLC discovery track invokes this addon automatically for persistent or
+exchanged data. Users should describe the data need; they need not choose a
+dialect, identifier, lifecycle, or compatibility policy themselves.
+
 ### Loops & iteration
 
 When the user needs an iterative coding loop, recursive context decomposition, eval gates, or guided autonomous implementation.

package/agentic/code/addons/aiwg-utils/skills/hook-status/SKILL.md

@@ -91,7 +91,7 @@ With `--verbose`, include hook file details:
 
 ## Workflow
 
-1. For each of the 8 providers, check context file existence
+1. For each provider returned by the authoritative provider registry, check context file existence
 2. If context file exists, grep for hook directive
 3. If directive found, check hook file existence
 4. Format output with status symbols

package/agentic/code/addons/aiwg-utils/skills/soul-status/SKILL.md

@@ -138,7 +138,7 @@ With `--verbose`, include additional detail:
 ## Workflow
 
 1. Locate SOUL.md (check `./SOUL.md`, `./.aiwg/SOUL.md`)
-2. For each of the 8 providers, check context file existence
+2. For each provider returned by the authoritative provider registry, check context file existence
 3. If context file exists, grep for `@SOUL.md` directive
 4. Check enforcement rule existence
 5. Scan for per-agent `.soul.md` files

package/agentic/code/addons/aiwg-utils/skills/steward/SKILL.md

@@ -319,7 +319,7 @@ exists in the production CLI.
 aiwg steward capabilities --all
 ```
 
-**Response**: Formatted table of all 9 providers x all 6 features, with native/emulated/unsupported indicators.
+**Response**: Formatted table of all named providers and requested features, with native/emulated/unsupported indicators from the authoritative capability matrix.
 
 ## Clarification Prompts
 

package/agentic/code/addons/aiwg-utils/skills/steward-quickref/SKILL.md

@@ -10,6 +10,7 @@ triggers:
   - select a persona
   - scaffold a project
   - steward routing
+  - steward capabilities
   - steward model routing
   - model catalog routing
   - cheap first model policy

package/agentic/code/addons/civic-action/README.md

@@ -10,26 +10,36 @@ content, or makes legal conclusions. Those transitions require named human
 review. A machine pass covers only the declared, schema-valid fields inspected
 by that command; it is not factual verification, compliance, or authorization.
 
-## Install and discover
-
-```bash
-aiwg use civic-action
-aiwg discover "plan a public records request"
-aiwg discover "reconcile a public meeting transcript with minutes"
-aiwg discover "publish cited local public information"
+## Ask the steward to set it up
+
+Start in your agent conversation. The steward can inspect the provider and
+workspace, preview the opt-in installation, preserve existing configuration,
+and verify the deployed agents, skills, flows, and gates:
+
+```text
+Act as the AIWG steward and set up Civic Action for this project. Inspect the
+current AIWG and provider configuration first. Explain whether you will enable
+the canonical civic-action addon directly or through an available provider
+plugin wrapper, preview every file or setting that will change, preserve local
+customizations, and ask for approval before writing. After setup, verify that
+the civic skills, agents, flows, templates, schemas, and validation gates are
+discoverable. Report any unavailable optional integration and its degraded
+mode. Do not submit, contact, record, identify, or publish anything.
 ```
 
-## Executable gates
+Then describe the civic outcome rather than selecting implementation commands:
 
-```bash
-aiwg civic source-gate source-registry.json
-aiwg civic meeting-gate vote-ledger.json reconciliation.json
-aiwg civic publish-gate publication-packet.json
+```text
+Plan a public records request for human review using authoritative sources and
+the correct jurisdiction. Preserve uncertainty, identify every required human
+decision, and stop before submission.
 ```
 
-All commands write a JSON report to stdout. Exit `0` means no blocking
-finding, exit `1` means one or more `block` findings, and exit `2` means invalid
-input or usage. Warnings remain in the report for human disposition.
+Advanced operators and automation can use the direct addon installation and
+gate commands documented in the
+[Civic Action CLI reference](https://docs.aiwg.io/pages/cli--reference.html#civic-action).
+Command results remain review evidence: they never authorize an external civic
+action.
 
 ## Capability map
 
@@ -45,9 +55,9 @@ input or usage. Warnings remain in the report for human disposition.
 | Local public resources | `local-resource-index`, CAP/GTFS/HSDS profile contract |
 
 Optional frameworks add research, transcription, knowledge-base, editorial,
-operations, and security capabilities. If absent, skills emit an explicit
-`blocked-dependency-missing` or `manual-review-required` state; they do not
-claim those checks ran.
+operations, and security capabilities. If absent, skills instruct the agent or
+reviewer to report a blocked dependency or manual-review requirement; they do
+not claim those checks ran.
 
-See `docs/overview.md`, `docs/quickstart.md`, and the cited research reports in
-`docs/research/` for the design basis and limitations.
+See `docs/overview.md`, the prompt catalog in `docs/quickstart.md`, and the cited
+research reports in `docs/research/` for the design basis and limitations.

package/agentic/code/addons/civic-action/commands/civic-action.mjs

@@ -3,8 +3,13 @@ import path from 'node:path';
 import { evaluateMeeting, evaluatePublication, evaluateSourceRegistry, exitCodeFor } from '../lib/gate-engine.mjs';
 import { assertCivicSchema, CivicSchemaValidationError } from '../lib/schema-validator.mjs';
 
+const MAX_INPUT_BYTES = 2 * 1024 * 1024;
+
 async function readJson(cwd, file) {
-  return JSON.parse(await fs.readFile(path.resolve(cwd, file), 'utf8'));
+  const absolute = path.resolve(cwd, file);
+  const metadata = await fs.stat(absolute);
+  if (metadata.size > MAX_INPUT_BYTES) throw new Error(`Civic input exceeds ${MAX_INPUT_BYTES} bytes: ${file}`);
+  return JSON.parse(await fs.readFile(absolute, 'utf8'));
 }
 
 export default async function civicAction(args, context = {}) {
@@ -38,7 +43,11 @@ export default async function civicAction(args, context = {}) {
       schema: 'aiwg.civic.gate-error.v1',
       code: error instanceof CivicSchemaValidationError ? error.code : 'CIVIC_INPUT_INVALID',
       error: error instanceof Error ? error.message : String(error),
-      ...(error instanceof CivicSchemaValidationError ? { validation_errors: error.validationErrors } : {}),
+      ...(error instanceof CivicSchemaValidationError ? {
+        validation_error_count: error.validationErrorCount,
+        validation_errors_truncated: error.validationErrorsTruncated,
+        validation_errors: error.validationErrors,
+      } : {}),
     };
     return { exitCode: 2, message: JSON.stringify(payload, null, 2) };
   }

package/agentic/code/addons/civic-action/docs/issue-traceability.md

@@ -1,5 +1,10 @@
 # Civic-action issue traceability
 
+> **Implementation reference.** Begin with the
+> [prompt-based Civic Action quickstart](quickstart.md) for user interaction.
+> Exact setup and validation syntax is maintained only in the
+> [CLI reference](https://docs.aiwg.io/pages/cli--reference.html#civic-action).
+
 | Issue | Implemented proof | Verification |
 |---|---|---|
 | #2213 legal/ethics guardrails | `rules/civic-safety.md`, `rules/publication-human-review.md`, jurisdiction template, cited legal brief, non-overridable source/publish gate findings | Source bypass and missing-review negative tests |

package/agentic/code/addons/civic-action/docs/overview.md

@@ -6,13 +6,37 @@ resource indexes, corrections, and publication review. It is an opt-in addon,
 not a jurisdiction database, law practice, autonomous newsroom, recorder, CMS,
 or outreach system.
 
+## Interaction model
+
+Users describe the civic outcome and evidence boundary in a prompt. The AIWG
+steward handles opt-in setup, capability discovery, dependency checks, and
+provider-safe deployment; the selected civic skill then creates reviewable
+artifacts and stops at the appropriate human gate.
+
+```text
+Act as the AIWG steward. Make Civic Action available for this project after
+previewing the setup and obtaining approval. Then help me plan an evidence-bound
+civic workflow for the material I provide. Establish jurisdiction and source
+authority, preserve uncertainty and citations, explain every warning or blocked
+condition, and stop before any submission, contact, recording, identification,
+or publication.
+```
+
+The [prompt-based quickstart](quickstart.md) provides focused asks for source
+review, public records, meetings, procurement, local resources, corrections,
+and publication. Direct setup and gate syntax is isolated in the
+[Civic Action CLI reference](https://docs.aiwg.io/pages/cli--reference.html#civic-action)
+for advanced operators and automation.
+
 ## Safety and evidence model
 
 The executable source, meeting, and publication commands validate their input
 schemas and block selected declared conditions, including access-control bypass,
 unresolved source authorization/rights, conflicted or unverified vote evidence,
 uncited declared material claims, incomplete named privacy/accessibility review,
-and missing named exact-hash publication approval. Broader jurisdiction,
+and missing independent, dated exact-hash publication approval. Publication
+claims use source/retrieval/selector citations, and empty claim or upstream-gate
+inventories cannot pass. Broader jurisdiction,
 consent, private/public status, anti-targeting, retention, and independent-review
 requirements are mandatory human workflow rules; the commands do not infer
 those facts from content.

package/agentic/code/addons/civic-action/docs/quickstart.md

@@ -2,44 +2,111 @@
 
 > **First time using AIWG?** Begin with [Install, Connect, and Verify](https://docs.aiwg.io/pages/getting-started--install-connect-verify.html). This guide assumes AIWG is already installed and connected to the target project.
 
-Install the opt-in addon:
+## Ask the steward to set up Civic Action
 
-```bash
-aiwg use civic-action
+Use the AIWG steward for the safest setup path. This prompt asks it to distinguish
+the canonical addon from any provider plugin wrapper, preview changes, and prove
+that the deployment works before civic work begins:
+
+```text
+Act as the AIWG steward and set up Civic Action for this project. Inspect the
+current AIWG and provider configuration first. Explain whether you will enable
+the canonical civic-action addon directly or through an available provider
+plugin wrapper, preview every file or setting that will change, preserve local
+customizations, and ask for approval before writing. After setup, verify that
+the civic skills, agents, flows, templates, schemas, and validation gates are
+discoverable. Report any unavailable optional integration and its degraded
+mode. Do not submit, contact, record, identify, or publish anything.
 ```
 
-Start with a natural-language ask:
+If you explicitly prefer terminal operation or automation, the
+[Civic Action CLI reference](https://docs.aiwg.io/pages/cli--reference.html#civic-action)
+shows the direct `use` setup and validation commands. The rest of this guide
+uses prompts because the steward and civic skills carry the safety context that
+bare commands do not.
+
+## Ask for an evidence-bound workflow
+
+Choose the prompt closest to your outcome and attach or identify the available
+source material. The agent should ask for missing jurisdiction and approval
+details instead of guessing them.
+
+### Review a public source
 
 ```text
-Plan a public records request for human review.
-Reconcile this public meeting transcript with the approved minutes.
-Review this public technology procurement using source-linked evidence.
-Index local emergency, transit, and human-service resources with citations.
-Run civic publication quality gates on this evidence packet.
+Review this public source before acquisition or reuse. Establish the publisher,
+jurisdiction, access method, authorization, current terms and publication
+rights, retrieval identity, freshness deadline, citation selector, fallback,
+and named human review. Treat unknown, stale, expired, or bypassed conditions
+as findings rather than assumptions. Return the source registry and gate report;
+do not acquire restricted material.
 ```
 
-For source acquisition, copy `templates/source-registry.yaml`, replace every
-unknown state with observed evidence, obtain named review, then run:
+### Plan a public-records request
 
-```bash
-aiwg civic source-gate source-registry.json
+```text
+Plan a public records request for human review. Research the applicable
+jurisdiction and existing public sources first, draft a narrow request, separate
+estimated dates from observed events, identify privacy and fee risks, and show
+the proposed tracking record. Stop before submission and ask a named person to
+approve the exact request.
 ```
 
-For meetings, preserve separate source media, transcript, ledger, and minutes
-artifacts. Do not replace `SPEAKER_XX` with a name without evidence and human
-confirmation:
+### Reconcile a public meeting
 
-```bash
-aiwg civic meeting-gate vote-ledger.json reconciliation.json
+```text
+Reconcile this public meeting's official source media, transcript, vote ledger,
+agenda, and approved minutes. Confirm recording and use are allowed for the
+jurisdiction before processing. Preserve speaker uncertainty, never infer an
+absent vote, distinguish draft from approved minutes, and cite every motion,
+vote, and material mismatch. Return the ledger and reconciliation packet for
+named human review; do not publish it.
 ```
 
-For publication, supply claim-level citations, privacy and accessibility
-reviews, correction state, upstream gates, and exact-hash human approval:
+### Review public technology
 
-```bash
-aiwg civic publish-gate publication-packet.json
+```text
+Review this public-technology procurement using primary public records and
+source-linked evidence. Inventory the relevant request, bid, contract, policy,
+meeting, payment, and oversight records; distinguish verified facts from claims;
+and map privacy, accessibility, security, interoperability, resilience, fiscal,
+and supplier risks to evidence. Do not rank vendors or recommend an award.
 ```
 
-Exit `0` means no machine block, not permission to publish. Exit `1` is a
-blocking result. Exit `2` is invalid input/usage. Human publication remains a
-separate external action.
+### Index local public resources
+
+```text
+Create a cited local-resource index from the authoritative CAP, GTFS, or HSDS
+source I provide. Preserve the original source and retrieval identities, bind
+the record to the correct format profile, validate freshness and public scope,
+and keep correction and takedown review visible. Report incomplete or unsafe
+records as blocked; do not present this as full standards conformance.
+```
+
+### Prepare a correction
+
+```text
+Review this proposed correction against the original and replacement artifacts.
+Identify every changed claim, supporting citation, affected downstream target,
+privacy or safety concern, and required revalidation. Preserve append-only
+version history and distinguish requested reindexing from observed completion.
+Return a correction record for independent human approval; do not publish it.
+```
+
+### Review a publication packet
+
+```text
+Review this civic publication packet for release readiness. Verify every
+material claim has a source, retrieval, and selector; inspect contrary evidence,
+freshness, privacy, accessibility, structured data, corrections, upstream gates,
+and deployment checks; and require independent, dated approval of the exact
+artifact hash. Report every warning and blocker. Do not publish anything.
+```
+
+## Expected handoff
+
+The agent should return the artifacts it created or updated, source-linked
+findings, gate results, unresolved assumptions, unavailable optional
+capabilities, and the named human decisions still required. A machine result
+with no blocker is not permission to submit, contact, record, identify, or
+publish. Those remain separate external actions.

package/agentic/code/addons/civic-action/docs/research/aiwg-design-patterns.md

@@ -1,5 +1,11 @@
 # AIWG design-pattern audit for the civic-action addon
 
+> **Research and maintainer reference.** Begin with the
+> [prompt-based Civic Action quickstart](../quickstart.md) for user interaction.
+> Commands below are verification evidence for maintainers; supported operator
+> syntax is maintained in the
+> [CLI reference](https://docs.aiwg.io/pages/cli--reference.html#civic-action).
+
 Status: implementation design input for AIWG issues #2213–#2222
 Repository audit date: 2026-09-01
 Scope: repository-native packaging, component contracts, composition, discovery,

package/agentic/code/addons/civic-action/docs/research/civic-workflow-standards.md

@@ -1,5 +1,10 @@
 # Civic workflow standards research brief
 
+> **Research reference.** Begin with the
+> [prompt-based Civic Action quickstart](../quickstart.md) for user interaction.
+> This brief supports the prompts and controls; it is not an operating guide or
+> a substitute for jurisdiction-specific human review.
+
 **Issues:** #2214, #2216, #2217, #2218, #2220, #2221
 **Retrieved:** 2026-09-01
 **Status:** implementation guidance; not legal advice

package/agentic/code/addons/civic-action/docs/research/control-source-matrix.md

@@ -1,5 +1,10 @@
 # Civic Action control-to-source matrix
 
+> **Control reference.** Begin with the
+> [prompt-based Civic Action quickstart](../quickstart.md) for user interaction.
+> This matrix explains the evidence behind each prompt and gate; it does not
+> authorize an external civic action.
+
 **Reviewed:** 2026-09-01
 
 **Scope:** AIWG Civic Action addon
@@ -16,15 +21,15 @@ is executable or declarative.
 | Control | Primary source basis | Shipped implementation | Verification | Boundary |
 |---|---|---|---|---|
 | Provenance and revision identity | [W3C PROV-DM](https://www.w3.org/TR/prov-dm/), [PROV-O](https://www.w3.org/TR/prov-o/) | Source, request, meeting, correction, and publication schemas carry identifiers, hashes, derivation, or version fields | Civic schema compilation and fixture tests | Most hashes are asserted metadata; the local gate does not fetch or independently hash remote evidence |
-| Catalog authority and freshness metadata | [W3C DCAT 3](https://www.w3.org/TR/vocab-dcat-3/), [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html), [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html) | Source registry records publisher, distribution, retrieval, validator, cache, and freshness fields | Source schema plus `source-gate` policy tests | Freshness is not correctness; jurisdiction policy remains a dated human determination |
+| Catalog authority and freshness metadata | [W3C DCAT 3](https://www.w3.org/TR/vocab-dcat-3/), [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html), [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html) | Source registry records publisher, distribution, retrieval, validator, cache, and freshness fields; the gate blocks unresolved jurisdiction sentinels and expired exceptions and reports overdue review | Source schema plus `source-gate` decision, deadline, exception, terms-snapshot, and next-review tests | Freshness is not correctness; jurisdiction policy remains a dated human determination |
 | Crawler and access review | [RFC 9309](https://www.rfc-editor.org/rfc/rfc9309.html) | Source gate checks declared robots, authorization, access, terms, publication-rights, and bypass states | Valid and hostile source fixtures; invalid schema inputs exit 2 | Robots permission is not legal authorization, copyright permission, or a security bypass license |
 | Public-records request planning | [U.S. DOJ request guidance](https://www.justice.gov/oip/make-foia-request-doj), [FOIA.gov FAQ](https://www.foia.gov/faq.html) | Request-plan schema/template separates estimated and observed dates, fixes automatic submission to false, and preserves original responses | Schema positives and consequential-action negatives | Federal FOIA is a reference pattern, not a substitute for state, local, tribal, territorial, or foreign law; no submission gate ships |
 | Meeting openness, recording, and official-record separation | [Massachusetts Open Meeting Law Guide](https://www.mass.gov/doc/open-meeting-law-guide-2025/download), [Florida Sunshine Manual](https://www.myfloridalegal.com/sites/default/files/government-in-the-sunshine-manual.pdf) | Meeting Flow requires a pre-recording human gate; ledger and reconciliation remain separate artifacts | Flow schema/human-gate tests; meeting packet gate | State examples are not universal law; recording posture is a declarative human gate, not determined by the CLI |
-| Transcript cues and selectors | [WebVTT](https://www.w3.org/TR/webvtt1/), [Media Fragments](https://www.w3.org/TR/media-frags/) | Vote ledger requires source cues, timestamps/citations, explicit verification, and conflict preservation | Inferred-vote, conflict, and missing-cue negative tests | The addon does not identify speakers or declare its reconciliation official minutes |
-| Accessibility review | [WCAG 2.2](https://www.w3.org/TR/WCAG22/), [WCAG-EM](https://www.w3.org/TR/WCAG-EM/) | Publication packet separates automated and manual status and requires a named manual reviewer | Publication gate negative tests | Automated checks and a packet status are evidence, not a WCAG conformance determination |
-| Public-technology evidence review | [FAR Part 10](https://www.acquisition.gov/far/part-10), [FAR Subpart 4.8](https://www.acquisition.gov/far/subpart-4.8), [FAR 9.104-1](https://www.acquisition.gov/far/9.104-1), [NIST SP 800-161r1](https://csrc.nist.gov/pubs/sp/800/161/r1/upd1/final) | Review schema inventories evidence, risk, release state, and human review; award recommendation is fixed to null | Schema positives and prohibited-award negative | Federal sources are design references unless adopted; the addon does not rank vendors, resolve conflicts of interest, or recommend an award |
-| Publication state and correction planning | [IPTC NewsML-G2 Guidelines](https://www.iptc.org/std/NewsML-G2/guidelines/), [Sitemaps protocol](https://www.sitemaps.org/protocol.html), [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html) | Correction record/template and publication packet preserve version and downstream states; publish gate blocks non-usable versions and unresolved declared propagation | Publication and correction schema tests; publication policy negatives | Correction is a human workflow, not a cryptographically enforced history; third-party reindexing or deletion cannot be guaranteed |
-| Emergency, transit, and human-service profiles | [OASIS CAP 1.2](https://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2.html), [FEMA IPAWS developers](https://www.fema.gov/emergency-managers/practitioners/integrated-public-alert-warning-system/technology-developers), [GTFS reference](https://gtfs.org/documentation/schedule/reference/), [Open Referral HSDS](https://docs.openreferral.org/en/latest/hsds/overview.html) | Local-resource schema has conditional CAP, GTFS, and HSDS profile fields plus provenance, citations, freshness, and declared validation state | Per-vertical schema positives and cross-profile negatives | These are AIWG profile contracts, not CAP/GTFS/HSDS conformance or public-safety validators |
+| Transcript cues and selectors | [WebVTT](https://www.w3.org/TR/webvtt1/), [Media Fragments](https://www.w3.org/TR/media-frags/) | Vote ledger requires a nonempty motion inventory, source cues, timestamps/citations, explicit verification, and conflict preservation; reconciliation requires comparisons and blocks unresolved material/unknown differences | Empty-inventory, inferred-vote, conflict, pending-difference, and missing-cue negative tests | The addon does not identify speakers or declare its reconciliation official minutes |
+| Accessibility review | [WCAG 2.2](https://www.w3.org/TR/WCAG22/), [WCAG-EM](https://www.w3.org/TR/WCAG-EM/) | Publication packet separates automated and manual status and requires a named, dated manual reviewer with a decision reason | Publication gate anonymous, undated, and incomplete-review negatives | Automated checks and a packet status are evidence, not a WCAG conformance determination |
+| Public-technology evidence review | [FAR Part 10](https://www.acquisition.gov/far/part-10), [FAR Subpart 4.8](https://www.acquisition.gov/far/subpart-4.8), [FAR 9.104-1](https://www.acquisition.gov/far/9.104-1), [NIST SP 800-161r1](https://csrc.nist.gov/pubs/sp/800/161/r1/upd1/final) | Review schema requires nonempty evidence and risk inventories with evidence references; award recommendation is fixed to null | Schema positives, empty-inventory negatives, and prohibited-award negative | Federal sources are design references unless adopted; the addon does not rank vendors, resolve conflicts of interest, or recommend an award |
+| Publication state and correction planning | [IPTC NewsML-G2 Guidelines](https://www.iptc.org/std/NewsML-G2/guidelines/), [Sitemaps protocol](https://www.sitemaps.org/protocol.html), [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html) | Publication requires nonempty claim/upstream-gate inventories, structured source/retrieval selectors, and independent dated exact-hash approval; correction records require changed claims and downstream targets | Publication and correction schema tests; vacuous-pass, self-review, state, and propagation negatives | Correction is a human workflow, not a cryptographically enforced history; third-party reindexing or deletion cannot be guaranteed |
+| Emergency, transit, and human-service profiles | [OASIS CAP 1.2](https://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2.html), [FEMA IPAWS developers](https://www.fema.gov/emergency-managers/practitioners/integrated-public-alert-warning-system/technology-developers), [GTFS reference](https://gtfs.org/documentation/schedule/reference/), [Open Referral HSDS](https://docs.openreferral.org/en/latest/hsds/overview.html) | Local-resource schema binds CAP/GTFS/HSDS verticals to their formats and prevents a declared publication pass for unverified, stale, nonpublic, unreviewed, or failed-validation records | Per-vertical, cross-profile, and unsafe-publication-state negatives | These are AIWG profile contracts, not CAP/GTFS/HSDS conformance or public-safety validators |
 | Human oversight and residual-risk disclosure | [NIST AI RMF 1.0](https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-ai-rmf-10) | Agents, rules, skills, and Flow gates reserve consequential decisions for named people and preserve warnings/blocks | Addon, Flow, CLI, discovery, and deployment tests | A machine pass is review evidence only; it is not legal advice, factual verification, compliance, or authorization to act |
 
 ## Citation maintenance gate

package/agentic/code/addons/civic-action/docs/research/legal-ethics-guardrails.md

@@ -1,5 +1,10 @@
 # Legal and ethics guardrails for civic-action workflows
 
+> **Research reference.** Begin with the
+> [prompt-based Civic Action quickstart](../quickstart.md) for user interaction.
+> These guardrails inform agent behavior and human review; they are not legal
+> advice or a jurisdiction-independent operating procedure.
+
 - **Issues:** [AIWG #2213](https://git.integrolabs.net/roctinam/aiwg/issues/2213), jurisdiction-sensitive portions of [AIWG #2216](https://git.integrolabs.net/roctinam/aiwg/issues/2216) and [AIWG #2217](https://git.integrolabs.net/roctinam/aiwg/issues/2217)
 - **Retrieved:** 2026-09-01
 - **Geographic baseline:** United States federal law and selected state examples; no state, tribal, territorial, or local conclusion is encoded

package/agentic/code/addons/civic-action/docs/research/synthesis-and-readiness.md

@@ -1,5 +1,10 @@
 # Civic-action research synthesis and readiness decision
 
+> **Decision record.** Begin with the
+> [prompt-based Civic Action quickstart](../quickstart.md) for user interaction.
+> This document records implementation readiness and boundaries; it is not a
+> command-led user procedure.
+
 **Decision date:** 2026-09-01
 **Issues:** #2213–#2222
 **Decision:** proceed with an opt-in addon and fail-closed human gates; reject

package/agentic/code/addons/civic-action/examples/invalid/publication-uncited.json

@@ -2,15 +2,16 @@
   "schema": "aiwg.civic.publication-packet.v1",
   "artifact_id": "unsafe-story",
   "artifact_hash": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
+  "prepared_by": "news-caster",
   "sections": [{"id": "body", "required": true, "content_length": 0, "record_count": 0, "minimum_count": 1, "freshness_state": "expired"}],
   "links": [{"url": "https://example.invalid/missing", "http_status": 404, "material": true}],
   "claims": [{"claim_id": "claim-1", "material": true, "status": "reported_allegation", "attributed": false, "freshness_state": "expired", "citations": []}],
-  "upstream_gates": [],
+  "upstream_gates": [{"gate_id": "source-compliance/unsafe-source", "status": "pass"}],
   "structured_data": {"status": "fail", "format": "NewsArticle", "errors": ["missing dateModified"]},
-  "privacy": {"status": "pending", "reviewer": null},
-  "accessibility": {"automated_status": "pass", "manual_status": "pending", "reviewer": null},
+  "privacy": {"status": "pending", "reviewer": null, "reviewed_at": null, "decision_reason": ""},
+  "accessibility": {"automated_status": "pass", "manual_status": "pending", "reviewer": null, "reviewed_at": null, "decision_reason": ""},
   "publication_state": "usable",
   "correction": {"open_blocking": true, "pending_reindex_targets": 2},
   "deployment": {"last_good_copy_state": "missing", "verification_state": "pending", "live_page_state": "pending", "sitemap_state": "pending", "reindex_state": "pending", "cache_state": "pending", "adapter": "vendor-neutral-static"},
-  "human_review": {"state": "pending", "reviewer": null, "artifact_hash": "sha256:7777777777777777777777777777777777777777777777777777777777777777"}
+  "human_review": {"state": "pending", "reviewer": null, "reviewer_role": null, "artifact_hash": "sha256:7777777777777777777777777777777777777777777777777777777777777777", "reviewed_at": null, "decision_reason": ""}
 }