Clarify CodingScaffold value proposition

CHANGELOG.md

@@ -13,6 +13,10 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   project onboarding recommend `uv tool install` or `pipx install` from the GitHub repo so users can
   run `coding-scaffold` from any project without activating the source checkout's virtual
   environment. The clone + editable install path remains documented for contributors.
+- **README now answers why CodingScaffold exists alongside one-command agent installers.** The intro
+  now highlights adaptive language/tool setup, shared reviewed knowledge, and repeatable team
+  workflows before the quick-start commands. Knowledge docs clarify that durable wiki pages should
+  be distilled and reviewed, not raw chat transcript dumps.
 
 ## [0.5.1] — 2026-05-19
 

README.md

@@ -6,6 +6,27 @@
 Local-first onboarding, configuration, and governance scaffolding for AI-assisted software
 development teams.
 
+## Why Use This If Agents Already Install In One Command?
+
+A coding-agent installer gives you a binary. CodingScaffold prepares the repo around that binary so
+the agent starts with the right project rules, context, model guidance, review flow, and team memory.
+
+The practical difference shows up after the first setup:
+
+- **Adaptive project setup:** `setup run` uses the programming language, project shape, privacy
+  preference, hardware/provider signals, and selected coding tool to generate different local files.
+  OpenCode gets native commands and agents; Claude Code and Codex get their own native project
+  guidance; other tools get focused adapter docs.
+- **A shared knowledge base:** session traces, decisions, useful prompts, project vocabulary, and
+  repeated agent patterns can be captured as Markdown, reviewed in Git, and promoted into a team
+  wiki instead of staying buried in one person's chat history.
+- **A repeatable team workflow:** the scaffold gives `doctor`, `pilot`, `session`, `eval`,
+  permissions, policy, skills, and onboarding manifests the same shape across projects, without
+  making the scaffold a runtime agent or sending prompts to a model.
+
+Use your preferred coding agent. Use CodingScaffold when you want that agent to behave consistently
+inside a real repo and when the useful lessons from each session should become reusable team context.
+
 ## 30-Second Start
 
 You need three commands today. The rest can wait.
@@ -493,6 +514,12 @@ the single source of truth; this table is a scannable summary.
 The knowledge base is Markdown-first so it works in GitHub, GitLab, local editors, OpenCode,
 Obsidian, and optional memory tools.
 
+It is deliberately not "dump every chat into the wiki." Session traces and raw notes are source
+material. The durable team wiki should contain compressed, abstracted, reviewed knowledge: decisions,
+project vocabulary, useful prompts, validated workflows, and links back to source notes when needed.
+If automatic chat ingestion is added later, it should create reviewable distilled proposals rather
+than saving raw transcripts as team truth.
+
 Plain Markdown:
 
 ```bash

docs/docs/index.md

@@ -20,6 +20,10 @@ CodingScaffold helps a project use existing coding agents without turning day on
 migration. It writes reviewable project-local files for agent instructions, provider hints,
 knowledge, policies, and workflows.
 
+Agent installers give you a command to run. CodingScaffold gives that command repo-specific
+context: language-aware setup, tool-specific adapter files, model/provider guidance, verification
+habits, and a Markdown knowledge base where session findings can become reviewed team wiki pages.
+
 For a new repo or a small team pilot, use only this:
 
 ```bash

docs/docs/wiki/FAQ.md

@@ -60,6 +60,20 @@ print, or collect secret values.
 Copilot is useful for completion and chat. CodingScaffold focuses on agentic workflows: inspect,
 plan, edit, verify, review, and preserve reusable team habits.
 
+## Why not just install a coding agent directly?
+
+You should install and use the coding agent your team likes. CodingScaffold is the repo layer around
+that agent: it generates language-aware and tool-specific guidance, points the agent at the right
+local context, names verification habits, and gives the team a shared knowledge structure. The agent
+does the coding work; CodingScaffold helps the project remember how that work should happen.
+
+## Does it automatically turn chats into wiki pages?
+
+No. Today it provides session traces, raw note folders, curated wiki pages, and
+`knowledge distill --review` proposals. Durable team knowledge should be compressed, abstracted,
+reviewed Markdown, not raw chat logs. If automatic ingestion is added later, it should summarize,
+redact, deduplicate, and propose updates for review before they become team wiki pages.
+
 ## Why Markdown for knowledge?
 
 Markdown works in Git, GitHub, GitLab, editors, Obsidian, and memory tools. It is easy to review

docs/docs/wiki/Knowledge-Base.md

@@ -136,6 +136,12 @@ coding-scaffold knowledge distill --target ~/dev/my-project --source raw --revie
 The first version is deterministic and review-first. It writes `.new` proposal files under
 `knowledge/wiki/` and never silently rewrites curated pages.
 
+Do not treat raw agent chats as durable team knowledge. If your workflow captures conversation
+output, distill it first: remove secrets and irrelevant history, compress repeated context, abstract
+the reusable decision or pattern, and review the proposal before promoting it into `wiki/`.
+Automatic chat ingestion, if added later, should follow that same proposal-first shape instead of
+writing raw transcripts into the shared wiki.
+
 ## Obsidian
 
 Obsidian mode keeps Markdown as the source of truth while adding vault structure, backlinks,

tests/test_docs_positioning.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_readme_answers_why_use_scaffold_before_quick_start() -> None:
+    text = (ROOT / "README.md").read_text(encoding="utf-8")
+
+    why_index = text.index("## Why Use This If Agents Already Install In One Command?")
+    start_index = text.index("## 30-Second Start")
+    assert why_index < start_index
+    assert "Adaptive project setup" in text
+    assert "A shared knowledge base" in text
+    assert "A repeatable team workflow" in text
+
+
+def test_docs_do_not_claim_raw_chat_ingestion_as_team_wiki() -> None:
+    readme = (ROOT / "README.md").read_text(encoding="utf-8")
+    faq = (ROOT / "docs" / "docs" / "wiki" / "FAQ.md").read_text(encoding="utf-8")
+    knowledge = (ROOT / "docs" / "docs" / "wiki" / "Knowledge-Base.md").read_text(
+        encoding="utf-8"
+    )
+
+    combined = "\n".join([readme, faq, knowledge])
+    assert "not raw chat" in combined
+    assert "reviewable distilled proposals" in combined
+    for verb in ("summarize", "redact", "deduplicate"):
+        assert verb in combined