loomrail 0.1.0-alpha.4 → 0.1.0

package/README.md

@@ -5,12 +5,13 @@
     <a href="https://loomrail.github.io/loomrail/">Website</a> ·
     <a href="docs/guides/GETTING-STARTED.md">Quick start</a> ·
     <a href="docs/guides/GETTING-STARTED.ru.md">Быстрый старт</a> ·
-    <a href="docs/README.md">Documentation</a>
+    <a href="docs/README.md">Documentation</a> ·
+    <a href="ROADMAP.md">Roadmap</a>
   </p>
   <p>
     <a href="https://github.com/loomrail/loomrail/actions/workflows/ci.yml"><img src="https://github.com/loomrail/loomrail/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-6173ff" alt="Apache 2.0 license" /></a>
-    <img src="https://img.shields.io/badge/status-pre--alpha-c58b20" alt="Pre-alpha status" />
+    <img src="https://img.shields.io/badge/status-stable-2f6b52" alt="Stable status" />
     <img src="https://img.shields.io/badge/Node.js-24.19-43853d" alt="Node.js 24.19" />
   </p>
 </div>
@@ -26,67 +27,95 @@ the source of truth.
 </picture>
 
 > [!IMPORTANT]
-> Loomrail is public pre-alpha software. New projects use **Auto**: an installed, authenticated Codex or Claude Code
-> CLI can be selected for new sessions and spend provider quota. To guarantee a zero-quota first run, choose **Mock**
-> in **Settings → AI provider** before starting the workflow. Loomrail never installs or signs into a provider,
+> Loomrail is Stable software for macOS on Apple Silicon. New projects use **Auto**, which selects only a
+> compatible, signed-in local
+> Codex CLI or Claude Code CLI. Loomrail does not ask for provider API keys or use separate API billing; a missing,
+> incompatible, or signed-out CLI blocks startup instead of falling back. Loomrail never creates provider credentials,
 > enables permission-bypass flags, commits, pushes, merges, or deploys for you. A task worktree is not an
-> operating-system sandbox.
+> operating-system sandbox. Windows and Linux live-provider execution is not supported by this release and fails closed;
+> Windows remains covered by source, browser and clean-install CI while its real local-CLI evidence is pending.
 
 ## Install and run safely
 
-Requirements: Node.js `>=24.19 <25`, macOS or Windows, and a browser on the same machine. Linux is best effort.
+Requirements: Node.js `>=24.19 <25`, macOS on Apple Silicon, a browser on the same machine, the isolated Chromium build
+managed by the installed Playwright package, and at least one official local agent CLI already signed in:
+
+- Codex: install the official CLI and run `codex login` once; or
+- Claude Code: install the official CLI and run `claude auth login` once.
+
+That login remains owned by the provider CLI. Loomrail detects it read-only and never asks you to copy an API key.
+Windows and Linux are not supported live-provider targets in this macOS-scoped Stable release.
 
 Start in a new empty directory, not inside a repository you care about:
 
+<!-- loomrail-guided-activation-v1:start -->
+
 ```bash
 mkdir loomrail-evaluation
 cd loomrail-evaluation
-npm install loomrail@next
-npx loomrail
+npm install --ignore-scripts loomrail@latest
+npx playwright install chromium
+npx loomrail try
 ```
 
+<!-- loomrail-guided-activation-v1:end -->
+
+The Chromium download is an explicit one-time installation for deterministic Browser QA. Loomrail never reuses your
+signed-in browser profile. `loomrail try` first checks the local CLI version and login read-only. If a required check
+fails it writes nothing and tells you whether to install, update, or sign in to that CLI. When ready, it states the
+local state/log side effects, starts the loopback daemon, and opens the guided route. Each later mutation remains a
+visible owner action.
+
 The launcher binds to `127.0.0.1`, opens a one-time authenticated URL, and stores state in local SQLite. Keep the
 terminal open and stop Loomrail with `Ctrl+C`.
 
 If the browser must not open automatically:
 
 ```bash
-npx loomrail --no-open --port 4176
+npx loomrail try --no-open --port 4176
 ```
 
 Open the printed URL on the same machine within 60 seconds. `--no-open` does not enable remote access.
 
-For a global launcher, use `npm install -g loomrail@next` and then `loomrail`. The project-local route above is
-recommended for evaluation because it keeps the selected pre-alpha channel visible.
+For a global launcher, use `npm install -g --ignore-scripts loomrail@latest`, run
+`npx playwright install chromium`, and then `loomrail try`.
+The project-local route above is recommended because it keeps Loomrail and its browser runtime isolated.
 
 ## First run
 
-1. Choose **Initialize demo workspace**.
-2. Open **Settings → AI provider** and choose **Mock** for the zero-quota walkthrough.
-3. Create a task with a concrete outcome and observable acceptance criteria.
-4. Move it to **Ready** and start the workflow.
-5. Open **Attention**, answer the blocking Human Request, and approve the explicit mock budget increase.
+1. Choose **Prepare demo workspace**.
+2. Choose **Codex CLI** or **Claude Code CLI** for this project.
+3. Create the exact guided task and move it to **Ready**.
+4. Start the guided workflow with the displayed Loomrail budget and model tier.
+5. Open **Attention**, answer any blocking Human Request, and review every explicit budget change.
 6. When acceptance appears in **Attention**, open its exact task, inspect Review and QA evidence, then accept the
    delivery or return it to work as the owner.
 
+The bundled web demo needs no second server: its deterministic QA step measures Loomrail's own local readiness
+endpoint on the selected port. Your repositories use an explicit `.loomrail/browser-qa.json` plan; see the
+[Browser QA guide](docs/guides/BROWSER-QA.md).
+
 The task, request, budget, evidence, and decision survive page reloads and Loomrail restarts. The
 [quick start](docs/guides/GETTING-STARTED.md) walks through the route in detail.
 
-## Your repository and live providers
+## Your repository and providers
 
-After the mock route works, the owner guide explains repository registration, Project Constitution review, task
-worktrees, change inspection, backup, and recovery:
+The guides explain repository registration, Project Constitution review, task worktrees,
+change inspection, backup, recovery, diagnostics, upgrade, and uninstall:
 
 - [Owner guide](docs/guides/USER-GUIDE.md)
 - [Руководство владельца](docs/guides/USER-GUIDE.ru.md)
+- [Operations guide](docs/guides/OPERATIONS.md) · [Эксплуатация](docs/guides/OPERATIONS.ru.md)
+- [Provider compatibility](docs/guides/PROVIDER-COMPATIBILITY.md) · [Совместимость провайдеров](docs/guides/PROVIDER-COMPATIBILITY.ru.md)
+- [Bundled samples and roles](docs/guides/SAMPLES.md) · [Встроенные примеры и роли](docs/guides/SAMPLES.ru.md)
 - [Reproducible full-route example](docs/examples/full-route/README.md)
 - [Security and trust boundaries](docs/security/THREAT-MODEL.md)
 
-Install and authenticate the provider CLI yourself, then start Loomrail normally. In **Settings → AI provider**, keep
-**Auto** to use an available signed-in CLI or choose Codex, Claude Code, or Mock explicitly for that project. Use
-**Check again** after installing or signing in; no extra launch command is required. `LOOMRAIL_PROVIDER` remains an
-optional process-wide override for automation and troubleshooting. Read the owner guide and threat model before
-exposing a repository to either live CLI.
+Install and sign in to an official provider CLI, then start Loomrail normally. In **Settings → AI provider**, use
+**Check again** to refresh readiness. Auto considers only compatible and authenticated local runtimes. An explicit
+unavailable provider remains visible and fails closed. `LOOMRAIL_PROVIDER` remains an optional process-wide override
+for automation and troubleshooting, but it does not bypass version checks, login, stage support, permissions, or
+budgets.
 
 Context7 is different from an AI provider: its exact-pinned MCP server ships with Loomrail. In **Settings → MCP
 connections**, choose **Review bundled Context7**; no global install or `npx` command is needed. Loomrail still requires
@@ -96,7 +125,15 @@ machine, so never include secrets, personal data, or proprietary code.
 ## Current boundary
 
 - Local browser UI, loopback daemon, and local SQLite state.
-- Auto-discovered or explicitly selected providers, plus a deterministic Mock route with no provider quota.
+- Explicit selection between the locally installed Codex CLI and Claude Code CLI, with no API-key route or synthetic
+  runtime fallback.
+- All six stages, including `IMPLEMENT` and `QA`, use the real selected local agent. Repository access goes only
+  through Loomrail's bounded workspace tools, and provider text alone is never treated as file or test evidence.
+- Local CLI token usage is reconciled after a session. Loomrail enforces time, turn, tool and output limits during
+  execution and can block later work from the durable ledger, but cannot promise an exact stop at a token boundary
+  inside the current provider session.
+- Up to three agent runs in parallel by default, with durable global, Project, provider, and workspace gates plus an
+  Agent Fleet view of active roles and exact queue reasons.
 - Project-scoped local MCP connections and a bundled, owner-approved Context7 preset.
 - A global, restart-safe Attention Inbox for Human Requests and acceptance deep-links across every Project.
 - A typed read-only tool SDK at `loomrail/plugin-sdk`; local registration still uses explicit C1 consent and grant.
@@ -134,6 +171,8 @@ pnpm test:e2e
 See [CONTRIBUTING.md](CONTRIBUTING.md), the [architecture overview](docs/architecture/OVERVIEW.md), and the
 [release guide](docs/RELEASE.md). Plugin authors should start with the
 [Plugin SDK guide](docs/guides/PLUGIN-SDK.md) or its [Russian version](docs/guides/PLUGIN-SDK.ru.md).
+Use the [structured issue chooser](https://github.com/loomrail/loomrail/issues/new/choose) for reproducible bugs or
+bounded product proposals; suspected vulnerabilities belong in the [private security channel](SECURITY.md).
 
 ## License