Document published npm setup and the first real task

README.md

@@ -4,6 +4,7 @@
 
 <p align="center">
   <a href="https://github.com/liolevx/noxroot/actions/workflows/ci.yml"><img src="https://github.com/liolevx/noxroot/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/noxroot"><img src="https://img.shields.io/npm/v/noxroot" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License: Apache-2.0"></a>
 </p>
 
@@ -29,10 +30,7 @@ Code, Cursor, OpenCode, Copilot CLI, and other coding agents.
 | Decisions and fixes disappear into old chats           | Useful lessons are proposed as Markdown and carried into future tasks once accepted |
 | The workflow depends on one coding tool                | The core works through a CLI, Markdown, JSON, and a command adapter                 |
 
-New chats do not require another `init`. Ordinary questions need no Noxroot task. Noxroot stays in
-the background until code-changing work needs it.
-
-Example task brief (illustrative excerpt):
+Example task brief:
 
 <p align="center">
   <img src="docs/assets/noxroot-terminal.png" alt="Example Noxroot task brief: preserve project filters on back navigation, with relevant files, related tests, and checks to run" width="800">
@@ -66,28 +64,29 @@ before it runs with `noxroot verify --plan`.
 
 ## Set up once
 
+Requires Node.js `>=22.12 <27` and npm. From your repository directory, inspect the proposed setup:
+
 ```bash
-npx noxroot@latest init
+npx noxroot@latest preview
 ```
 
-Then keep talking to your coding agent normally:
+When ready, initialize once:
 
-```text
-Fix project filters resetting on back navigation.
+```bash
+npx noxroot@latest init
 ```
 
-For a code-changing task, compatible agents are instructed to use the pinned repository commands
-behind the scenes:
+Commit the reviewed setup before your first code-changing task; `start` requires a clean Git
+baseline.
 
-```bash
-npx --yes noxroot@0.1.0 start "fix project filters resetting on back navigation"
-# your existing coding agent builds the change
-npx --yes noxroot@0.1.0 finish
-```
+Then keep talking to your coding agent normally. Ask for your own feature, fix, or refactor. For
+code-changing tasks, compatible agents are instructed to run `start` before editing and `finish`
+when the change is ready to check, using the version pinned in your repository.
 
 Run `init` once per repository. It previews a thin managed entrypoint, preserves existing
-documentation, and pins the Noxroot version. The pinned `npx` command needs no global or project
-installation.
+documentation, and pins the Noxroot version. `npx` downloads the package into npm's cache; no global
+installation or clone of Noxroot is needed. The package is available on
+[npm](https://www.npmjs.com/package/noxroot).
 
 Before setup, preview labels each capability `create`, `reuse`, `adjacent`, `conflict`, or
 `not-assessed`. Noxroot creates only a confirmed gap. Existing systems stay in place. Missing
@@ -97,11 +96,18 @@ review, and learning. A coordination ledger or session journal is reported as ad
 preserve work across sessions, but Noxroot does not import its log or treat it as a development
 coordinator.
 
-Questions, explanations, reviews, and other read-only work do not create tasks. If a new
-conversation continues the same task in the same repository, branch, and worktree, `start` reuses
-the active baseline instead of creating a duplicate. `finish` finds the task when exactly one
-matches. If several tasks match, Noxroot lists them and requires `--task <id>` instead of guessing.
-Instruction discovery varies by coding tool, so the commands remain available for manual use.
+Read-only work creates no task. In the same repository, branch, and worktree, a repeated `start`
+continues the active baseline. `finish` infers a single matching task; several matches require
+`--task <id>`. Commands remain available for manual use when an agent does not follow the
+instructions.
+
+When upgrading, inspect the managed instruction changes with
+`npx noxroot@latest sync --dry-run --diff`. Apply them with `npx noxroot@latest sync` after review.
+Starting a new chat does not require an upgrade or another initialization. See the
+[command reference](docs/commands.md) for manual tasks and sync limits.
+
+For the first change, continuation, and troubleshooting, read
+[Getting started](docs/getting-started.md).
 
 ### What setup can add
 
@@ -121,10 +127,8 @@ remains discoverable without being copied.
 Existing `.git/noxroot` records stay in place, without a second store. If an agent cannot write task
 state, it must stop and request access before continuing.
 
-`SKILL.md` files are portable, on-demand instructions. The generated verification skill tells an
-agent how to check a change; the independent-review and optional product/UX skills describe their
-reviews. Context loading comes from `AGENTS.md`, the knowledge index, and context routes, not a
-generated context skill. Learning comes from `finish` and `learn`, not a generated learning skill.
+`SKILL.md` files are portable instructions for verification and review. `AGENTS.md`, the knowledge
+index, and routes guide context loading. `finish` and `learn` handle learning proposals.
 
 Skills are instructions, not test evidence. Incomplete work cannot become approved. Noxroot does not
 push, merge, publish, or deploy.
@@ -136,7 +140,13 @@ permission to edit. "Do not deploy" remains an exclusion; it never activates dep
 Large files get bounded line ranges when relevant text is found. Partial context is labelled; agents
 still inspect the surrounding code. Existing routes stay unchanged.
 
-## Try the read-only diagnosis
+## Preview example
+
+`preview` reports what Noxroot found and what setup would add. Use `preview --diff` to inspect the
+proposed patches before writing anything.
+
+<details>
+<summary>See a sample preview and run it from source</summary>
 
 To try Noxroot from source, use Node.js `>=22.12 <27`:
 
@@ -175,17 +185,17 @@ Next
   npx --yes noxroot@0.1.0 preview --diff
 ```
 
-Use `preview --diff` to inspect every proposed setup patch. The intended beta entry point is
-`npx noxroot@latest preview`.
+</details>
+
+For local development and validation commands, see [Development](docs/development.md).
 
 ## Portable by design
 
 Noxroot's universal interface is the CLI plus generated Markdown and JSON. Any agent that can run a
 command or read a task package can use it. The generic adapter accepts an explicit executable and
 literal arguments. It does not guess vendor flags or use shell interpolation.
 
-Instruction discovery varies by client. Some tools read `AGENTS.md`, others use their own files, and
-some require manual invocation. Noxroot does not claim equal native integration everywhere.
+Instruction discovery varies by client. Native integration is not identical across tools.
 
 Application-agent frameworks are detected project architectures, not competitors or dependencies.
 Their tests and evals can become approved repository checks. Noxroot does not install or control
@@ -204,9 +214,9 @@ Python, Go, Rust, and other stacks. CI covers Windows, macOS, and Linux.
 `learn --task ID` shows confirmable durable proposals. Data commands support `--json`, with progress
 and diagnostics on standard error.
 
-Read the [command reference](docs/commands.md), [configuration](docs/configuration.md),
-[architecture](docs/architecture.md), [adapter protocol](docs/adapters.md), and
-[security boundaries](docs/security.md).
+Read [Getting started](docs/getting-started.md), the [command reference](docs/commands.md),
+[configuration](docs/configuration.md), [architecture](docs/architecture.md),
+[adapter protocol](docs/adapters.md), and [security boundaries](docs/security.md).
 
 Noxroot is an experimental v0.1 MVP. Apache-2.0; see [CONTRIBUTING.md](CONTRIBUTING.md),
 [SECURITY.md](SECURITY.md), and [LICENSE](LICENSE).

docs/adapters.md

@@ -1,5 +1,10 @@
 # Agent and verification adapters
 
+You do not need to configure an adapter to use Noxroot with your existing coding agent. After setup,
+compatible agents follow the repository instructions and call the CLI themselves. Command adapters
+let Noxroot launch optional delegated workers through `run` or automated reviewers through `run` and
+`finish`.
+
 ## Manual
 
 The default adapter emits the complete task package for use in any agent or chat. It reports zero
@@ -14,6 +19,10 @@ receives one JSON line on standard input:
 { "role": "worker", "taskPackage": { "task": "..." } }
 ```
 
+The executable must understand this protocol. A vendor CLI name alone does not make it compatible;
+use documented arguments or a wrapper that translates the task package. Install and authenticate
+that tool separately. Noxroot does not supply provider accounts, credentials, or model access.
+
 Roles are `worker`, `repair`, and `reviewer`. An automated reviewer must write exactly one JSON
 object to standard output with `decision`, `summary`, `findings`, and `learningCandidates`. Findings
 require severity, evidence, and required outcome; optional paths are repository-relative. Prose,

docs/architecture.md

@@ -3,8 +3,13 @@
 Noxroot is one Node.js/TypeScript package. The CLI layer parses input and keeps machine output
 separate from diagnostics. Core functions return typed values and do not write implicitly. Detection
 uses bounded filesystem APIs, groups repeated monorepo evidence, and never runs project code or an
-LLM. Proposal generation produces complete file contents and unified creation patches.
-Initialization is the only component that applies those proposals.
+LLM. Proposal generation produces complete file contents and unified creation patches. The shared
+setup writer applies those proposals for `init` and `sync`.
+
+The npm package runs locally; distribution does not add a hosted service or a second agent. In the
+normal workflow, an existing coding agent invokes `start` and `finish` through repository
+instructions. The optional `run` adapter is a separate delegated workflow, not an onboarding
+requirement. New CLI versions do not silently migrate task state or replace repository-owned rules.
 
 Root `AGENTS.md` and `CLAUDE.md` remain instruction evidence when Git ignores them. Explicit
 sensitive-path exclusions and symlink protections still apply. Ordinary ignored files stay excluded.

docs/commands.md

@@ -1,5 +1,14 @@
 # Command reference
 
+## Run from npm
+
+From your repository directory, run `npx noxroot@latest preview` to inspect setup without writing
+files, then `npx noxroot@latest init` when ready. Requires Node.js `>=22.12 <27` and npm.
+
+Commands below use `noxroot` as shorthand. Without a global installation, use
+`npx --yes noxroot@0.1.0` in its place, or the version pinned in your repository instructions.
+Compatible agents handle `start` and `finish`; you do not need to type them for each conversation.
+
 ## Global behavior
 
 `noxroot --help`, `noxroot <command> --help`, and `noxroot --version` are stable discovery surfaces.
@@ -38,9 +47,10 @@ to one contained project with `--root` before initialization.
 
 ## `init` and `sync`
 
-`init` creates only files in the reviewed proposal. It checks every target again before writing,
-writes each file through a same-directory temporary file, and rolls back files it created if the
-operation fails. Existing files are never overwritten.
+`init` applies only reviewed file creations and managed patches. It checks every target before
+writing, guards patches with the reviewed content hash, and writes through same-directory temporary
+files. On failure it attempts to restore patched files and remove newly created files. Unmanaged
+content is preserved; setup is not a transaction against concurrent filesystem changes.
 
 Explicitly referenced project knowledge, task routes, Agent Skills, and documented verification
 wrappers are reused rather than copied. Noxroot does not integrate with or replace an existing
@@ -70,11 +80,15 @@ does not broadly rewrite the repository.
 
 ## `context`
 
-`context "task"` shows the outcome, a bounded selection of paths, likely source and tests, approved
-checks with their working directories, an exclusion count, and estimated tokens. Exclusions and
-conflicts remain visible. `--verbose` adds every selected path, selection reasons, individual
+`context "task"` shows the outcome, a bounded selection of paths, relevant files and related tests,
+approved checks with their working directories, an exclusion count, and estimated tokens. Exclusions
+and conflicts remain visible. `--verbose` adds every selected path, selection reasons, individual
 exclusions, unknowns, and byte counts. JSON retains the complete bounded context package.
 
+The human headings are `Relevant files`, `Related tests`, and `Checks to run`. Selection is
+advisory; listed checks have not run. JSON keeps the existing `likelyOwningSource`, `likelyTests`,
+and `requiredVerification` fields.
+
 Large source and test files can be selected as up to three line ranges rather than whole files.
 Human output labels these as partial. JSON adds `lineRanges` (one-based, inclusive) and
 `sourceBytes`; `bytes` counts only the selected ranges. These are reading hints, not embedded code

docs/configuration.md

@@ -3,6 +3,10 @@
 `.noxroot/config.yml` uses schema version 1. Invalid values produce a file and field path. Versions
 other than 1 are rejected instead of guessed.
 
+Start with the configuration proposed by `init`; do not replace it with this reference example.
+Schema version `1` is separate from the npm package version. Updating the CLI does not authorize new
+checks or rewrite your task routes.
+
 ```yaml
 version: 1
 modules:
@@ -20,7 +24,7 @@ autonomy:
   merge: 0
   delivery: 0
 agents:
-  default: local-agent
+  default: manual
   adapters:
     manual:
       type: manual
@@ -49,6 +53,12 @@ browser:
     - { name: mobile, width: 390, height: 844 }
 ```
 
+The optional `local-agent` entry illustrates the adapter shape, not working flags for a particular
+coding tool. Leave `manual` selected for the normal workflow where your existing agent calls
+Noxroot. Command adapters are optional for delegated workers or automated review; see the
+[adapter protocol](adapters.md). The sample `browser-e2e` id must refer to a check you actually
+approved before enabling `browser`.
+
 Autonomy is enforced, never descriptive-only: level 0 permits read-only diagnosis/context/plans;
 implementation level 1 permits guided records; implementation level 2 permits a configured worker;
 review level 3 permits independent reviewer and bounded repair calls. Higher configured values are

docs/development.md

@@ -38,8 +38,13 @@ Before adding a dependency, explain why a platform API is insufficient. Producti
 limited to command parsing, schema validation, and YAML. Before claiming a new project shape or
 adapter, add a realistic fixture and failure-path coverage.
 
-Publication is not part of ordinary development. The owner must first create the npm package,
-configure npm trusted publishing for the exact GitHub repository/workflow on a GitHub-hosted runner,
-and authorize adding a publish workflow with `id-token: write`. Do not create or store a long-lived
-npm publication token. Trusted publishing automatically supplies provenance for eligible public
-packages.
+When working inside the Noxroot source checkout, use `node dist/cli.js` after building. `npx` can
+resolve this checkout's package instead of the registry package, without an installed command shim.
+
+`noxroot@0.1.0` is published on npm. Publication is not part of ordinary development. Future
+automated releases require the owner to configure npm trusted publishing for the exact GitHub
+repository and workflow, and authorize a publish workflow with `id-token: write` on a GitHub-hosted
+runner. That workflow is not configured yet. Do not create or store a long-lived npm publication
+token. Trusted publishing supplies provenance for eligible public packages; the first manual release
+does not have that provenance. npm's displayed README updates only when a new package version is
+published.

docs/getting-started.md

@@ -0,0 +1,93 @@
+# Getting started
+
+Use Noxroot in a repository you already work on, with your usual coding agent. You need Node.js
+`>=22.12 <27`, npm, and a Git repository with a committed baseline for code-changing tasks. No
+global Noxroot installation is required.
+
+## 1. Preview your repository
+
+Open a terminal in your project directory:
+
+```bash
+npx noxroot@latest preview --diff
+```
+
+Noxroot shows what it found, what it would reuse, and the exact files setup would change. Preview
+does not modify the project or run its commands. npm may download the CLI first.
+
+Check that it found your existing instructions and documentation. Look at proposed verification
+commands and their working directories. Missing evidence should remain visible, not become a guessed
+command. For a repository of independent examples, select one project with `--root`.
+
+## 2. Confirm setup once
+
+```bash
+npx noxroot@latest init
+```
+
+Review the patches and approve only what belongs in this repository. Existing documentation stays in
+place. Compatible agent instructions receive a pinned Noxroot command.
+
+Review and commit the accepted setup changes before the first code-changing task. `start` requires a
+clean committed Git baseline. Keep unrelated edits separate; do not discard them to make the working
+tree clean.
+
+If another coordinator owns development work, Noxroot can offer companion setup for context and
+verification. It does not take over that coordinator's lifecycle, reviews, or learning.
+
+## 3. Ask your agent for a real change
+
+Choose a small feature, fix, or refactor you already need. Describe it normally, including anything
+the agent must not change. You do not need a Noxroot-specific prompt.
+
+In full mode, compatible agents are instructed to:
+
+1. Run `start` before editing to record a baseline and receive the task brief.
+2. Inspect the relevant files and project rules, then make the change.
+3. Run `finish` to check the actual diff and report remaining gaps or required review.
+
+Noxroot does not install native client hooks. Instructions guide agents; they cannot guarantee
+compliance. For your first task, check the agent's command history for `start` and `finish`. If they
+are missing, ask it to follow the repository instructions. See the [command reference](commands.md)
+for manual use.
+
+## 4. Check the result
+
+The handoff should name the changed files, commands that ran, failures, and anything unverified.
+Passing checks do not satisfy a required review. A task with incomplete verification is not
+approved.
+
+Useful lessons can be proposed for documentation after the task. Review those proposals before
+applying them. No learning candidate is a valid outcome; every change does not need another
+document.
+
+For your first few tasks, ask:
+
+- Did the brief surface a relevant rule or file without loading unrelated material?
+- Did the checks catch a problem or provide evidence you can inspect?
+- Was useful knowledge reused next time, without duplicating existing docs?
+
+These are usefulness checks, not a requirement to keep a session journal.
+
+## Continue later
+
+Open the same repository, branch, and worktree and keep working with your agent. Repeating `start`
+for the same active task continues its baseline. A new chat needs neither another `init` nor a task
+for ordinary questions. Local task state is not chat restoration or cross-machine synchronization.
+
+## If something looks wrong
+
+Use the pinned version from your repository instructions. For the first release:
+
+```bash
+npx --yes noxroot@0.1.0 doctor
+npx --yes noxroot@0.1.0 status
+```
+
+`doctor` checks configuration; it does not prove your agent follows instructions. `status` shows
+active tasks and next actions. If task-state writes are blocked, stop before editing and approve
+only the required access. Do not disable the sandbox. If several tasks match, select the intended
+task instead of guessing.
+
+For upgrades, review the [sync procedure](commands.md#init-and-sync). For Noxroot's own source
+checkout, use the [development instructions](development.md).