Merge pull request #4 from grainulation/docs/v2.0.0-release

Restore README identity and finish v2.0.0 documentation

Author: aid-ninja

CONTRIBUTING.md

@@ -1,77 +1,70 @@
 # Contributing to Grainulator
 
-Thanks for your interest in contributing to the Grainulator plugin.
-
-## What Grainulator is
-
-Grainulator is a Claude Code plugin that packages skills, agents, and
-hook wiring for research-sprint workflows. It's distributed via the
-grainulation marketplace, not npm.
+Grainulator provides evidence, memory, exports, and portable workflows through a CLI and one MCP server. Use it with any compatible host; Claude Code and Codex also have native plugin integrations. The v2.0.0 source is distributed through GitHub. The root npm package and component workspaces are private, so a GitHub release does not publish them to npm.
 
 ## Getting started
 
-```bash
+Use Node.js 24 or later; Node 25 is the development default in `.nvmrc` and `.node-version`.
+
+```sh
 git clone https://github.com/grainulation/grainulator.git
 cd grainulator
-npm install
+npm ci --ignore-scripts
+node bin/grainulator.js doctor
 npm test
 ```
 
-The plugin expects to run inside Claude Code. For local smoke-testing,
-install it as a development plugin:
+For a direct MCP connection, `node bin/grainulator.js connect --dir /absolute/path/to/project` prints configuration without changing host settings. For a local Claude plugin check, use the tested invocation:
 
-```bash
-# From inside Claude Code
-/plugin install /path/to/local/grainulator
+```sh
+claude --plugin-dir /absolute/path/to/grainulator
 ```
 
+For native Codex, install the intended local plugin through its marketplace mechanism and launch with `GRAINULATOR_WORKSPACE=/absolute/path/to/project codex`. Follow [plugin acceptance](docs/PLUGIN-TESTING.md) for installation, workspace binding, exact build verification, and actual host/subagent tool checks. Direct MCP success does not prove full plugin discovery.
+
 ## Filing issues
 
-- Search existing issues before opening a new one.
-- For bugs, include reproduction steps, your Claude Code version, and
-  relevant MCP server logs (from `~/.claude/logs/`).
-- For feature requests, describe the use case and what existing skill
-  or command would have been relevant.
+- Include reproduction steps, expected and observed behavior, Node and host versions, and the source revision or installed build ID.
+- Include relevant redacted tool errors or traces. Remove credentials and private task content before sharing.
+- For feature requests, describe the user task and the limitation of the current workflow.
 
 ## Pull requests
 
-1. Fork the repo and create a branch from `main`.
-2. If you're adding or changing a skill, update the skill's `SKILL.md`
-   and any relevant test.
-3. Run `npm test`; add tests if you're adding functionality.
-4. Keep PRs focused — one change per PR.
-5. Use Biome for formatting: `npx biome format --write .` before
-   committing (CI enforces this).
+1. Create a focused branch from `main` and preserve existing user data and compatibility boundaries.
+2. Update the relevant instructions when commands or behavior change. Add meaningful regression coverage for changed functionality.
+3. Run `npm test` and `npm run lint`, plus the checks relevant to your change. Use `npx biome format --write <changed-files>` for files covered by the repository's Biome configuration.
+4. Describe the problem, resulting behavior, checks actually run, and remaining limits. Do not report older test results as verification of newer edits.
 
-## End-to-end tests
+## Verification and CI
 
-`npm test` runs the unit suite and is what CI gates on. Playwright
-e2e runs locally only — not in CI — out of the maintainer's ranch
-harness. Keeping it local keeps browser tooling out of this repo's
-dep tree and keeps CI fast.
+CI runs `npm test`, `npm run build:site`, `npm run check:package`, and `npm run test:install` on Node 24 and 25. Separate jobs run lint, Rust runtime conformance, and the Playwright static-site check on Node 25. Browser tooling is a development dependency in this repository.
 
-## Skills
+```sh
+npm run lint
+npm run test:install
+npm run test:runtime
+npx playwright install chromium
+npm run test:static
+```
+
+Rust/Cargo is required for runtime conformance; Python 3 and Playwright Chromium are required for the static-site test. `npm run test:site` additionally exercises the local preview, playground, demo, scrolling, and organization site. Start `npm run dev` for the preview-dependent checks; see [deployment and browser checks](docs/DEPLOYMENT.md). Paid-provider and native-host tests require the relevant credentials and are separate from CI's static and synthetic checks.
 
-Skills live in `skills/<name>/SKILL.md`. Each skill is one markdown
-file with YAML frontmatter (`name`, `description`, `tools`) and a
-prompt body. Keep tools lists minimal — only what the skill actually
-needs.
+## Skills and shared templates
 
-Shared snippets live under `templates/` (files prefixed `_`
-are not loaded as skills). Reference them from a SKILL.md with the
-`${CLAUDE_PLUGIN_ROOT}/templates/<file>` path.
+Skills live in `skills/<name>/SKILL.md`, with YAML metadata and a portable Markdown workflow. Every directory under `skills/` must contain a real skill. Declare only needed tools; distinguish direct and host-prefixed MCP names where the host requires an allowlist.
 
-## Version bumps
+Shared artifact templates live in root `templates/`, outside skill discovery. Claude can resolve `${CLAUDE_PLUGIN_ROOT}/templates/<file>`; other hosts resolve templates relative to the installed plugin or checkout. Preserve the documented accessibility shell when customizing artifacts.
 
-Grainulator uses `npm version <patch|minor|major>` which runs the
-`version` script automatically — it syncs the new version into
-`.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`
-and stages them so the bump commit is complete.
+## Version preparation
 
-## Security
+Prepare a version change without automatically creating a Git commit or tag:
+
+```sh
+npm version <patch|minor|major> --no-git-tag-version
+```
 
-See `SECURITY.md` for private-disclosure channels.
+The version lifecycle synchronizes and stages `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json`, and root `plugin.json`. Review those changes alongside `package.json` and `package-lock.json`, then commit through the normal review flow. `npm run sync-version` alone updates manifest contents without staging them. Create a release tag only after required CI passes and the release is authorized. Npm publication is a separate action; the packages remain private.
 
-## Code of conduct
+## Security and conduct
 
-See `CODE_OF_CONDUCT.md`.
+See [SECURITY.md](SECURITY.md) for private disclosure and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community expectations.

README.md

@@ -1,120 +1,153 @@
-# Grainulator
+<p align="center">
+  <a href="https://grainulator.app"><img src="site/glitchy.png" alt="Glitchy — the Grainulator mascot" width="200"></a>
+</p>
 
-Evidence and verification for the model you already use.
+<h1 align="center">Grainulator</h1>
 
-Grainulator gives model-assisted work a local evidence ledger, checks for contradictions and weak support, and turns the remaining gaps into concrete next actions. Use it for research, engineering, or a managed command loop with a verifier that measures your task.
+<p align="center"><strong>Evidence and verification for the model you already use.</strong></p>
 
-**Grainulator 2.0.0** is distributed through the [v2.0.0 GitHub release](https://github.com/grainulation/grainulator/releases/tag/v2.0.0). This GitHub release is not published to npm. Use the tagged source and [dogfood guide](docs/DOGFOOD.md) to run it locally; existing repository history and stars are preserved.
+<p align="center">
+  Keep the evidence. Challenge the answer. Know what to do next.<br>
+  A shared workflow for research, engineering, and model-assisted work.
+</p>
 
-## Start locally
+<p align="center">
+  <a href="https://grainulator.app/playground/"><img src="https://img.shields.io/badge/explore_the_playground-grainulator.app-98f3ef?style=for-the-badge" alt="Explore the Grainulator playground"></a>
+</p>
 
-Requires Node.js 24 or later; Node 25 is the local default:
+<p align="center">
+  <a href="https://github.com/grainulation/grainulator/releases"><img src="https://img.shields.io/github/v/release/grainulation/grainulator?label=release" alt="Latest GitHub release"></a>
+  <a href="https://github.com/grainulation/grainulator/actions/workflows/ci.yml"><img src="https://github.com/grainulation/grainulator/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI on main"></a>
+  <a href="docs/INSTALLATION.md"><img src="https://img.shields.io/badge/node-%E2%89%A524-339933?logo=nodedotjs&logoColor=white" alt="Node.js 24 or later"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
+  <a href="https://deepwiki.com/grainulation/grainulator"><img src="https://deepwiki.com/badge.svg" alt="Docs on DeepWiki"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="docs/INSTALLATION.md">Installation</a> ·
+  <a href="docs/TOOLS.md">Tools</a> ·
+  <a href="docs/PLUGIN-TESTING.md">Agent setup</a> ·
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
+
+---
+
+## What it adds
+
+Good models still need a way to keep track of evidence, revisit assumptions, and verify their work. Grainulator gives them that process, with a local ledger that stays with the task as it moves between models and sessions.
+
+| Capability | What it gives you |
+| --- | --- |
+| **Evidence that stays with the work** | Typed claims, sources, evidence tiers, and provenance that survive edits and exports. |
+| **A check on the answer** | Conflict detection, weak-support signals, and explicit gaps to investigate. |
+| **Clear next actions** | Two lists: what the agent can continue automatically, and what needs your input. |
+| **Sessions you can carry forward** | Configurable research, stop/resume, reusable context, and credential-free exports. |
+| **Verification for your task** | A managed command loop that can use a verifier you provide. |
+
+**One package, one MCP server.** Use the CLI, connect an MCP-compatible agent, or load the bundled Claude Code or Codex plugin. The consolidated components are included; separate ecosystem installations are not required.
+
+## Quick start
+
+Requires **Node.js 24+**. Node 25 is the development default.
 
 ```sh
 git clone --branch v2.0.0 https://github.com/grainulation/grainulator.git
 cd grainulator
 npm ci --ignore-scripts
 node bin/grainulator.js doctor
-node bin/grainulator.js init --dir ./sprints/example \
-  --question 'Can this change meet our requirements?' \
-  --audience engineers --constraints 'Preserve existing user data' \
-  --done 'Implemented and verified, with remaining limits documented'
-node bin/grainulator.js connect --dir ./sprints/example
+node bin/grainulator.js preview
 ```
 
-`connect` prints configuration for one **grainulator** MCP server. It changes no host settings. Load that configuration in your host, or keep using the CLI. The portable [Grainulator workflow](skills/grainulator/SKILL.md) can be read by any agent; Claude Code also supports the bundled skills and hooks.
+Open **[localhost:4517/playground/](http://127.0.0.1:4517/playground/)** to choose your model, configure the workflow, and run research with your provider key.
 
-## Call tools
+Want to look around first? The **[public playground](https://grainulator.app/playground/)** lets you explore the controls and export a setup. Model execution happens in your local installation.
 
-The public server is `grainulator`. Tool names describe the operation:
+> **Distribution:** v2.0.0 is a [GitHub release](https://github.com/grainulation/grainulator/releases/tag/v2.0.0), not an npm registry release. For a separate local installation, follow the [archive installation guide](docs/INSTALLATION.md).
 
-```js
-// MCP server: grainulator, tool: add_claim
-{
-  "dir": ".",
-  "id": "r001",
-  "type": "constraint",
-  "topic": "delivery",
-  "content": "Do not tag the release before required CI checks pass.",
-  "evidence": "stated"
-}
+### Connect your agent
+
+From the project you want Grainulator to access:
+
+```sh
+node /path/to/grainulator/bin/grainulator.js connect --dir "$PWD"
 ```
 
-In host interfaces that combine server and tool names, this appears as `grainulator.add_claim` or `mcp__grainulator__add_claim`.
+Register the printed MCP configuration in your host, then restart its connection. The command prints configuration; it does not change your host settings.
 
-| Capability | Tools |
-| --- | --- |
-| Evidence | `init`, `add_claim`, `compile`, `search`, `status`, `resolve` |
-| Memory | `memory_search`, `memory_store`, `memory_list`, `memory_pull` |
-| Exports | `exports_convert`, `exports_formats`, `exports_preview` |
+For bundled skills, agents, and hooks, use the **[native plugin setup guide](docs/PLUGIN-TESTING.md)**. Native Codex requires an absolute `GRAINULATOR_WORKSPACE` in its process environment. CLI and direct MCP access remain available to other hosts.
 
-The CLI equivalent is `grainulator add --dir <sprint> ...`. See [host setup](docs/HOSTS.md) and the [adapter contract](docs/ADAPTERS.md). External connectors are optional; local evidence operations do not require them.
+## Put it to work
 
-## How work progresses
+With Grainulator connected, give your agent the outcome you need:
 
-1. Investigate the question that matters to the requested outcome. Record supported findings with their sources and evidence tiers.
-2. Compile the ledger to surface material conflicts, weak evidence and missing perspectives. Resolve what can be resolved, and preserve honest limitations.
-3. Implement and verify the requested artifact. Run another investigation only when it can change a decision or close a relevant gap.
+> Use Grainulator to investigate whether we should migrate this service. Record the evidence, challenge the assumptions, implement the agreed changes, and verify them. Keep the remaining next steps split into Auto and Manual.
 
-There are no fixed research-pass or claim-count quotas. A compiler result is evidence about the ledger, not proof that every claim is true or that the whole task is complete. Independent tests establish only what they actually check.
+The work follows a simple cycle:
 
-Next actions appear as two concise lists:
+1. **Record** findings with their sources and evidence tiers.
+2. **Check** for conflicts, weak support, and missing perspectives.
+3. **Act** on the gaps that matter, then verify the requested result.
+4. **Continue** from the saved ledger or export the session to another workflow.
 
-**Auto**
+There are no fixed claim-count or research-pass quotas. **Auto** lists work the agent can continue within your authorization. **Manual** lists decisions, access, or actions that need you. When you ask only for next steps, those two lists are the entire response.
 
-- Work the agent can continue under existing authorization.
+<details>
+<summary><strong>Example: record a claim from the terminal</strong></summary>
 
-**Manual**
+```sh
+node bin/grainulator.js init --dir ./sprints/migration \
+  --question 'Should we migrate this service?' \
+  --audience engineers --constraints 'Preserve existing user data' \
+  --done 'A verified plan with remaining risks documented'
 
-- Decisions, access or actions that require you; `None.` when there are none.
+node bin/grainulator.js add --dir ./sprints/migration \
+  --id r001 --type constraint --topic migration \
+  --content 'Existing user data must remain readable.' --evidence stated
 
-The agent continues authorized Auto work. Compiler suggestions never grant permission or override the task’s scope. When you ask for next steps only, those two lists are the entire response.
+node bin/grainulator.js compile --dir ./sprints/migration
+```
 
-## Playground and managed sessions
+The equivalent MCP tool is **`add_claim`** on the **`grainulator`** server. See the [tool reference](docs/TOOLS.md) for evidence, memory, export, analytics, and orchestration operations.
 
-Run `npm run dev` and open the printed local URL. The research playground supports model and provider configuration, evidence controls, and portable session export/resume. See [research sessions](docs/RESEARCH.md) for configuration and continuation.
+</details>
 
-`node bin/grainulator.js demo` exercises a deterministic adapter and verifier offline. It demonstrates the execution protocol; it is not evidence that a model produces better answers. See [evaluation results](docs/EVALUATION.md) for measured model behavior and limits.
+## Explore the docs
 
-## Repository
+| Guide | Start here for… |
+| --- | --- |
+| [Installation](docs/INSTALLATION.md) | Tagged source, isolated archives, and verified build identity. |
+| [Agent setup](docs/PLUGIN-TESTING.md) | Claude Code, Codex, and actual plugin acceptance checks. |
+| [Research sessions](docs/RESEARCH.md) | Models, feature controls, credentials, export, and resume. |
+| [Tools](docs/TOOLS.md) | The canonical CLI and MCP interface. |
+| [Execution adapters](docs/ADAPTERS.md) | Attaching a model command and a task-specific verifier. |
+| [Architecture](docs/STRUCTURE.md) | The workspace layout and internal modules. |
+| [Evaluation](docs/EVALUATION.md) | What has been measured and what remains unproven. |
+| [Contributing](CONTRIBUTING.md) | Development setup, tests, and changes to the project. |
 
-```text
-bin/                  Public CLI
-lib/                  Research, providers and execution loop
-packages/
-  evidence/           Claims and compilation
-  memory/             Source context and retrieval
-  exports/            Documents and presentations
-  analytics/          Sprint metrics and reports
-  orchestration/      Sprint dependencies
-  runtime/            Managed execution and verification
-  shared/             Common utilities
-  legacy-cli/         Compatibility commands
-skills/               Portable workflows
-agents/               Agent instructions
-hooks/                Host evidence reminders and write guard
-site/                 Product site and playground
-scripts/              Previews and acceptance checks
-test/                 Plugin and integration regressions
-evals/                Model evaluations
-```
+## Verification and limits
 
-The permission dashboard has been removed. Native hosts own permissions and remote access. Grainulation’s organization site lives in its separate checkout. Retained internal package identifiers and accepted legacy tool aliases support existing integrations; they are not separate products. [Source provenance](docs/source-imports.json) records the imports.
+CI checks Node 24 and 25, isolated package installation, plugin contracts, Rust runtime conformance, lint, and the static playground in a browser. Native host and live-provider acceptance have separate [verification guides](docs/READINESS.md).
 
-The single Grainulator package includes the consolidated components; separate ecosystem installations are not required.
+The compiler checks the structure and support recorded in the ledger; it does not establish that a source is true. Evaluations do not establish a general accuracy or efficiency gain, and per-pass limits are not a whole-session spending cap. Keep those distinctions when interpreting results.
 
-## Verify from a source checkout
+<details>
+<summary><strong>Run the development checks</strong></summary>
 
 ```sh
 npm test
 npm run test:install
 npm run lint
 ```
 
-See the [dogfood guide](docs/DOGFOOD.md) for browser and runtime checks, and [readiness](docs/READINESS.md) for release acceptance. The GitHub release and locally packed archives do not publish an npm package.
+Browser and runtime prerequisites are in [CONTRIBUTING.md](CONTRIBUTING.md). The offline `node bin/grainulator.js demo` exercises the adapter/verifier protocol without a provider account.
 
-## License
+</details>
 
-MIT. See [LICENSE](LICENSE).
+---
 
-Local dogfood uses Node 25 (`.nvmrc` / `.node-version`); Node 24 is the minimum supported runtime.
+<p align="center">
+  Built by <a href="https://grainulation.com">Grainulation</a> ·
+  <a href="LICENSE">MIT licensed</a> ·
+  <a href="https://github.com/grainulation/grainulator/issues">Issues & ideas</a>
+</p>