Pre-deployment adoption cleanup #60

New issue

Closed

opened 2026-09-09 20:56:37 +00:00 by kilo · 0 comments

kilo commented

2026-09-09 20:56:37 +00:00

Member

Goal

Reduce informational bureaucracy and adoption friction before the first deployment by making the product-facing documentation answer the current user journey while preserving technical provenance and historical evidence.

Why

The repository exposes too much M0-M3 construction history to normal adopters. Users should be able to understand, run, integrate, and safely evaluate Scarcity Router without first reading milestone, issue, PR, decision, or acceptance-gate history.

Scope

Audit README.md, AGENTS.md, .kilo/rules/, docs/, model-policy.json, model-catalog.json, and examples/*.
Rewrite README.md around the implemented current user experience: value proposition, quick start, capacity checks, selection, MCP, providers, privacy/product boundary, documentation, and development.
Establish a concise human documentation map distinguishing USE IT, UNDERSTAND IT, DEVELOP IT, and AUDIT/HISTORY.
Make the main documentation path product and current technical documentation; keep decisions, roadmap, POC evidence, M3 acceptance, calibration, and competitive material as provenance/history without deleting evidence.
Remove time-dependent status and duplicated durable rules from AGENTS.md while preserving workflow, security, provider-edge, validation, bounded-review, and human-merge invariants.
Review .kilo/rules/* for only clear verbatim duplication.
Perform a bounded stale-language pass over current technical docs and keep explicitly historical sections intact.
Do not split or redesign model-policy.json.

Acceptance Criteria

README.md presents implemented software and a usable current path, with MCP prominent and no milestone/issue/PR/decision storytelling in the normal onboarding path.
The documentation map clearly separates USE IT, UNDERSTAND IT, DEVELOP IT, and AUDIT/HISTORY, and normal adopters can ignore the latter two categories.
AGENTS.md contains durable rules only and retains all security and bounded-orchestration invariants.
Historical evidence is preserved, including docs/m3-acceptance.md contents.
model-catalog.json, model-policy.json, scarcity_router/, provider collectors, and runtime-semantic tests are unchanged.
Changed Markdown links are valid.
uv sync --only-dev, make check, uv run basedpyright, and git diff --check pass.
One feature branch and one Forgejo PR target develop; the PR remains open and unmerged.

Constraints

Editorial and information-architecture cleanup only; no selector, capacity, catalog, policy runtime, collector, CLI, REST, MCP, package, or runtime behavior changes.
Preserve provenance and avoid unnecessary path-moving/link churn; do not undertake a full ADR migration.
No live provider calls are required.
Keep the model-policy boundary unchanged; record any future configuration separation only as a deferment if needed.

Links

## Goal Reduce informational bureaucracy and adoption friction before the first deployment by making the product-facing documentation answer the current user journey while preserving technical provenance and historical evidence. ## Why The repository exposes too much M0-M3 construction history to normal adopters. Users should be able to understand, run, integrate, and safely evaluate Scarcity Router without first reading milestone, issue, PR, decision, or acceptance-gate history. ## Scope - Audit README.md, AGENTS.md, .kilo/rules/*, docs/*, model-policy.json, model-catalog.json, and examples/*. - Rewrite README.md around the implemented current user experience: value proposition, quick start, capacity checks, selection, MCP, providers, privacy/product boundary, documentation, and development. - Establish a concise human documentation map distinguishing USE IT, UNDERSTAND IT, DEVELOP IT, and AUDIT/HISTORY. - Make the main documentation path product and current technical documentation; keep decisions, roadmap, POC evidence, M3 acceptance, calibration, and competitive material as provenance/history without deleting evidence. - Remove time-dependent status and duplicated durable rules from AGENTS.md while preserving workflow, security, provider-edge, validation, bounded-review, and human-merge invariants. - Review .kilo/rules/* for only clear verbatim duplication. - Perform a bounded stale-language pass over current technical docs and keep explicitly historical sections intact. - Do not split or redesign model-policy.json. ## Acceptance Criteria - README.md presents implemented software and a usable current path, with MCP prominent and no milestone/issue/PR/decision storytelling in the normal onboarding path. - The documentation map clearly separates USE IT, UNDERSTAND IT, DEVELOP IT, and AUDIT/HISTORY, and normal adopters can ignore the latter two categories. - AGENTS.md contains durable rules only and retains all security and bounded-orchestration invariants. - Historical evidence is preserved, including docs/m3-acceptance.md contents. - model-catalog.json, model-policy.json, scarcity_router/, provider collectors, and runtime-semantic tests are unchanged. - Changed Markdown links are valid. - `uv sync --only-dev`, `make check`, `uv run basedpyright`, and `git diff --check` pass. - One feature branch and one Forgejo PR target `develop`; the PR remains open and unmerged. ## Constraints - Editorial and information-architecture cleanup only; no selector, capacity, catalog, policy runtime, collector, CLI, REST, MCP, package, or runtime behavior changes. - Preserve provenance and avoid unnecessary path-moving/link churn; do not undertake a full ADR migration. - No live provider calls are required. - Keep the model-policy boundary unchanged; record any future configuration separation only as a deferment if needed. ## Links - [Repository](https://forgejo.creatidy.com/BioMedical-IT/scarcity-router) - [Documentation directory](https://forgejo.creatidy.com/BioMedical-IT/scarcity-router/src/branch/develop/docs)

kilo referenced this issue from a pull request that will close it,

2026-09-09 21:22:11 +00:00

Docs: streamline pre-deployment adoption path #61