Clarify freview quickstart, current readiness and documentation navigation

README.md

@@ -10,12 +10,37 @@ freview is a portable, evidence-first [Agent Skill](https://agentskills.io/) for
 
 It produces a review, not a cleanup script. Default operations are **read-only**.
 
-> **Status:** Pre-release read-only preview for trusted repositories; **no version has been tagged or published**. Installation and native discovery depend on agent/runtime configuration. A Full review is not a security certification or physical-device verification.
+> **Status:** Usable from source; **pre-release, no version has been tagged or published**. Standard/Full repository audits are **read-only by default**; optional execution, mutation testing and repair workflows require separate explicit authorization. The bundled tests pass on Ubuntu/macOS, but native skill activation and real provider or mutation workloads must be checked in the target environment.
 
-**Integrated on `main`:** [evidence reconciliation #16](https://github.com/raiseCatError/freview/pull/16), [optional operations #17](https://github.com/raiseCatError/freview/pull/17), [structured adversarial verdicts #18](https://github.com/raiseCatError/freview/pull/18), [verification isolation #19](https://github.com/raiseCatError/freview/pull/19), and [mutation quality / bounded autonomy #20](https://github.com/raiseCatError/freview/pull/20). All five have been merged with their development history retained; [the integrated CI run](https://github.com/raiseCatError/freview/actions/runs/39019289770) passed on Ubuntu and macOS. **This is still pre-release:** real provider, mutation workload and physical-host acceptance are separate from synthetic CI.
+**Integrated on `main`:** evidence reconciliation, isolated operations, structured adversarial reviews, mutation scoring and bounded autonomy. All six development/standardization PRs [#16–#21](https://github.com/raiseCatError/freview/pulls?q=is%3Apr+is%3Amerged) are merged. [Final integration CI](https://github.com/raiseCatError/freview/actions/runs/39019711917) passed on Ubuntu and macOS. The implementation is **not** a production sandbox or a guarantee of correct agent reviews.
 
 **Dogfooding:** [final pre-release freview-on-freview review](docs/audits/2026-10-17-final-pre-release-self-review.md) · [historical original audit](docs/freview-reviews-freview.md). The newer source review is a bounded, hosted-evidence **partial-audit**, not native invocation in the author's agent session.
 
+## Quick start
+
+Install the skill into the coding-agent environment where you want to use it:
+
+```sh
+npx skills add raiseCatError/freview --skill freview
+```
+
+Open or reload your agent in the target repository, verify freview appears in its **native skill list**, then invoke `/freview` where the client supports that syntax, or ask for **“freview standard”**. The skill defaults to a **read-only Standard repository check**. `freview` here is an agent skill, **not a new shell executable**. Check your agent's specific discovery behavior in [Installation](#install) and the [acceptance checklist](docs/testing/agent-activation-acceptance.md).
+
+For an overview of documentation, configuration, optional mutation/autonomy and troubleshooting, see the [documentation index](docs/README.md).
+
+## Features at a glance
+
+| What you want | freview capability | Default behavior |
+| --- | --- | --- |
+| A factual repository health check | Quick / Standard: Git state, PRs/issues, release readiness, docs, CI and duplicate work items | **Read-only**, Standard |
+| A deeper source review | Full: examine implementation reachability, quality, tests and evidence gaps | Read-only; Full only when requested |
+| Check whether “done” is supported | Reconcile exact-SHA CI, requirements, claims and missing evidence | Claims never become proof automatically |
+| Compare automated review results | Bounded structured adversarial findings and repair stages | **Off** until explicitly configured |
+| Evaluate test strength | Optional Stryker/mutmut mutation reports and regression sensitivity | **Off**; optional quality gates |
+| Coordinate implementation | Bounded worker/reviewer loops and recovery checkpoints | **Off**; scratch copies, no automatic merge or release |
+
+Read the [mode guide](skills/freview/references/modes.md) for scope and the [operations guide](skills/freview/references/optional-ops.md) for explicit permissions. Optional execution in a scratch copy **does not** constitute an OS sandbox.
+
 ## Install
 
 One portable skill: `skills/freview/SKILL.md`, with references and an optional Python-standard-library snapshot helper.

docs/README.md

@@ -0,0 +1,40 @@
+# freview documentation
+
+Start with the [README](../README.md) for installation, everyday usage and feature overview. freview is an **evidence-first repository auditor**: the default skill is read-only. Its separately configured operations companion can run tools only after explicit authorization.
+
+## Where to go
+
+| Goal | Documentation |
+| --- | --- |
+| Install into Claude Code, Codex, OpenCode or Antigravity | [Installation and quick start](../README.md#quick-start), [agent discovery and limitations](../skills/freview/references/agent-discovery.md) |
+| Understand Quick, Standard and Full | [Review modes](../skills/freview/references/modes.md), [freview skill](../skills/freview/SKILL.md) |
+| Interpret local Git status versus remotely observable facts | [Local state and worktrees](../skills/freview/references/local-state.md), [Git analysis](../skills/freview/references/git.md) |
+| Check spec completeness and independent verification evidence | [Evidence reconciliation](../skills/freview/references/evidence-reconciliation.md), [verification ground truth](testing/evidence-ground-truth.md) |
+| Configure a normal read-only audit | [Project configuration](../skills/freview/references/configuration.md), [audit policy schema](../schemas/freview-config.schema.json) |
+| Configure explicitly authorized automated operations | [Operations manual](../skills/freview/references/optional-ops.md), [operations policy schema](../schemas/freview-ops.schema.json), [default-safe example](../examples/freview-ops.example.json) |
+| Understand adversarial review claims and interruption recovery | [Reviewer verdict and checkpoints](../skills/freview/references/review-verdict-protocol.md) |
+| Use mutation quality, repair budgets and quality gates | [Mutation and autonomy guide](../skills/freview/references/mutation-autonomy.md) |
+| Generate or interpret review findings | [Report format](../skills/freview/references/report.md), [remediation](../skills/freview/references/remediation.md) |
+| Configure daily, optional checks | [Automation](../skills/freview/references/automation.md) |
+| Diagnose installation/agent discovery | [Agent doctor and paths](../skills/freview/references/agent-discovery.md), [native activation acceptance checklist](testing/agent-activation-acceptance.md), [support](../SUPPORT.md) |
+| Contribute or report a problem | [Contributing](../CONTRIBUTING.md), [support](../SUPPORT.md), [security reporting](../SECURITY.md) |
+| See the evidence and historical development record | [Audit archive](audits/README.md), [historical roadmaps](roadmap/) |
+
+## Two different configurations
+
+**`.freview.json`** is optional, non-executable audit preference data. It can help choose the scope and branches for a normal read-only review. It never grants permission to run project scripts.
+
+**`.freview-ops.json`** is an entirely separate, versioned policy for *opt-in* operations: trusted worker and reviewer commands, tests, mutation tools, local hooks and a shipping **handoff**. Every execution-capable module is disabled by default. Enabling a module in a file alone cannot grant execution permission; runtime execution requires explicit user authorization, a clean exact-SHA checkout and caller-selected scratch storage. Never assume that copying the example turns autonomy on.
+
+## Current readiness and limitations
+
+- **Usable from source now:** the skill, reference documents and Python 3/Git helpers are on `main`. No versioned GitHub release has been published. Use the [installation instructions](../README.md#quick-start) and verify native skill discovery in the actual client.
+- **Verified in CI:** the bundled assets, schema contracts, deterministic helper tests and isolated fake-agent workflows have passed Ubuntu and macOS matrix checks for the integrated `main` branch.
+- **Not established by CI:** live Claude/Codex/OpenCode/Antigravity invocation for every supported client, real Stryker/mutmut workloads, arbitrary external tool safety, production deployment and physical Mac/SSD acceptance. They remain **acceptance gates for claims about those environments**, not evidence that the default read-only skill has failed.
+- **Security boundary:** scratch copies are not operating-system sandboxes; a configured executable may still access other files and the network. Keep untrusted code outside optional execution unless separately sandboxed.
+
+## Historical documents versus current state
+
+The [audit archive](audits/README.md) and `docs/roadmap/` are **Historical** records. A dated entry that says a PR was a draft or unmerged describes its state *at that checkpoint*, not its current GitHub state. Feature PRs [#16](https://github.com/raiseCatError/freview/pull/16) through [#20](https://github.com/raiseCatError/freview/pull/20), plus the configuration-standardization [#21](https://github.com/raiseCatError/freview/pull/21), have since merged into `main`.
+
+Do not silently rewrite source-level audit findings, past SHAs or test evidence. Verify current Git refs and CI separately when making a present-day claim.

docs/audits/README.md

@@ -2,6 +2,8 @@
 
 An evidence log, **not a list of software features or an endorsement of any agent report**.
 
+> **Current-state note (2026-10-17):** This table is a chronological archive. References to "draft", "unmerged", or an unfinished gate refer to the **historical checkpoint**, not today's branch or PR status. Feature PRs [#16–#20](https://github.com/raiseCatError/freview/pulls?q=is%3Apr+is%3Amerged), plus standardization PR [#21](https://github.com/raiseCatError/freview/pull/21), have now merged into `main`. The [final integrated main CI](https://github.com/raiseCatError/freview/actions/runs/39019711917) succeeded on Ubuntu and macOS. This does **not** retroactively turn any earlier partial audit into a completed live-agent or mutation-engine validation. See the [current documentation map](../README.md).
+
 | Audit | Observation | Scope and caveats |
 | --- | --- | --- |
 | [Historical freview-on-freview audit (draft PR #8)](https://github.com/raiseCatError/freview/pull/8) | AGY 1.4.0 / Gemini 3.8 Flash High | Full-mode native source review, verified local helper execution; **manual SKILL.md activation**, not native AGY injection; agent audit marked `partial-audit`. Preserve original baseline and later tested SHA. |

tests/test_docs_navigation.py

@@ -0,0 +1,55 @@
+"""Documentation navigation stays valid and describes the integrated state."""
+from pathlib import Path
+import re
+import unittest
+from urllib.parse import unquote
+
+ROOT = Path(__file__).resolve().parents[1]
+ENTRYPOINTS = (
+    ROOT / "README.md",
+    ROOT / "docs" / "README.md",
+    ROOT / "docs" / "audits" / "README.md",
+    ROOT / "skills" / "freview" / "references" / "configuration.md",
+    ROOT / "skills" / "freview" / "references" / "optional-ops.md",
+    ROOT / "skills" / "freview" / "references" / "mutation-autonomy.md",
+)
+LINK = re.compile(r"(?<!!)\[[^\]]*\]\(([^)]+)\)")
+
+
+class DocumentationNavigationTests(unittest.TestCase):
+    def test_entrypoint_markdown_targets_exist(self):
+        for source in ENTRYPOINTS:
+            with self.subTest(source=source.relative_to(ROOT)):
+                self.assertTrue(source.is_file())
+                content = source.read_text(encoding="utf-8")
+                for raw in LINK.findall(content):
+                    destination = raw.split(" #", 1)[0].strip().strip("<>")
+                    if not destination or destination.startswith(
+                        ("#", "http:", "https:", "mailto:", "data:")
+                    ):
+                        continue
+                    # A link can include a title after its relative path.
+                    relative = unquote(destination.split(" \"", 1)[0].split("#")[0])
+                    target = (source.parent / relative).resolve()
+                    with self.subTest(path=relative):
+                        self.assertTrue(target.is_relative_to(ROOT.resolve()))
+                        self.assertTrue(target.exists(), f"{source}: {relative}")
+
+    def test_documentation_index_explains_both_configs(self):
+        doc = (ROOT / "docs" / "README.md").read_text(encoding="utf-8")
+        self.assertIn(".freview.json", doc)
+        self.assertIn(".freview-ops.json", doc)
+        self.assertIn("Historical", doc)
+        self.assertIn("read-only", doc.lower())
+
+    def test_readme_has_an_actionable_quickstart(self):
+        readme = (ROOT / "README.md").read_text(encoding="utf-8")
+        self.assertIn("## Quick start", readme)
+        self.assertIn("## Features at a glance", readme)
+        self.assertIn("docs/README.md", readme)
+        self.assertNotIn("Pre-release read-only preview", readme)
+        self.assertIn("no version has been tagged", readme.lower())
+
+
+if __name__ == "__main__":
+    unittest.main()