docs: sharpen first-contact story and onboarding

CONTRIBUTING.md

@@ -193,6 +193,33 @@ SpecFact CLI uses **Spec-Driven Development (SDD)** via [OpenSpec](./openspec/)
 - Test documentation examples
 - **Update OpenSpec specs**: When implementing features, ensure [`openspec/specs/`](./openspec/specs/) reflects the new behavior
 
+### Entry-Point Messaging Hierarchy
+
+The repository README, `docs/index.md`, and other first-contact surfaces must preserve the same
+first-contact story.
+
+When editing those surfaces, make sure a new visitor can quickly answer:
+- **What is SpecFact?**
+- **Why does it exist?**
+- **Why should I use it?**
+- **What do I get?**
+- **How do I get started?**
+
+Keep the hierarchy in this order:
+1. Product identity
+2. Why it exists
+3. User value
+4. How to get started
+5. Deeper topology and cross-site handoff
+
+For first-contact pages, define SpecFact as the validation and alignment layer for software delivery
+and present “keep backlog, specs, tests, and code in sync” as the user-visible outcome of that
+positioning.
+
+GitHub-facing repo metadata must reinforce the same story. Keep the repository description, topics,
+and other above-the-fold cues aligned with the README hero so visitors see the same product
+identity before and after opening the repository.
+
 ### Documentation Structure
 
 - `README.md`: Project overview and quick start

README.md

@@ -1,8 +1,9 @@
 # SpecFact CLI
 
-> **The "swiss knife" CLI that turns any codebase into a clear, safe, and shippable workflow.**
-> Keep backlog, specs, tests, and code in sync so changes made by people or AI copilots do not break production.
-> Works for brand-new projects and long-lived codebases - even if you are new to coding.
+> **SpecFact is the validation and alignment layer for software delivery.**
+> It adds the missing validation layer that keeps backlog intent, specifications, tests, and code
+> from drifting apart across AI-assisted coding, brownfield systems, and governed delivery.
+> Use it to move fast without losing rigor.
 
 **No API keys required. Works offline. Zero vendor lock-in.**
 
@@ -23,21 +24,54 @@ invoke SpecFact as part of a command chain.
 
 ---
 
-## Documentation Topology
+## What is SpecFact?
 
-`docs.specfact.io` is the canonical docs entry point for SpecFact.
+SpecFact is the validation and alignment layer for software delivery.
 
-- Core CLI/runtime/platform documentation remains owned by `specfact-cli`.
-- Module-specific deep docs are canonically owned by `specfact-cli-modules`.
-- The live modules docs site is currently published at `https://modules.specfact.io/`.
+It is a local CLI that helps you keep the intent behind a change aligned from
+backlog or idea through specifications, implementation, and checks. The “Swiss-knife CLI” metaphor
+fits because SpecFact gives you a set of focused tools for specific delivery problems, not a vague
+bag of features.
 
-Use this repository's docs for the overall SpecFact workflow, CLI runtime lifecycle, module registry, trust model, and command-group topology.
-Use the modules docs site for bundle-specific deep dives, adapter details, workflow tutorials, and module-authoring guidance.
-In short, module-specific deep docs are canonically owned by `specfact-cli-modules`.
+In practice, SpecFact helps you:
+- add guardrails to AI-assisted and fast-moving greenfield work
+- reverse-engineer large brownfield codebases into trustworthy structured understanding
+- reduce the “I wanted X but got Y” drift between backlog, spec, and implementation
+- move from local rigor toward team and enterprise policy enforcement
 
----
+## Why does it exist?
+
+Modern delivery drifts in predictable ways:
+- AI-generated quick wins often lack the validation layer needed for mid- and long-term reliability
+- brownfield systems often have missing or drifted specs, so teams need to reverse-engineer reality
+- backlog intent gets reinterpreted into something else before it reaches code
+- teams working with different skill levels, opinions, and AI IDE setups need consistent review and
+  policy enforcement
+
+SpecFact exists to reduce that drift. It helps teams understand what is really there, express what
+should happen more accurately, and validate that the result still matches the original intent.
+
+## Why should I use it?
+
+Use SpecFact if you want one of these outcomes:
+- ship AI-assisted changes faster without accepting fragile “looks fine to me” quality
+- understand a legacy or unfamiliar codebase before changing it
+- hand brownfield insight into OpenSpec, Spec-Kit, or other spec-first workflows
+- keep backlog expectations, specifications, and implementation from silently diverging
+- enforce shared rules consistently across developers and CI/CD
 
-## Start Here (60 seconds)
+## What do I get?
+
+With SpecFact, you get:
+- a deterministic local CLI instead of another opaque SaaS dependency
+- a validation layer around fast-moving implementation work
+- codebase analysis and sidecar flows for brownfield understanding
+- stronger backlog/spec/code alignment for real delivery workflows
+- a path from individual rigor to organization-level policy enforcement
+
+## How do I get started?
+
+### Start Here (5 minutes)
 
 ### Install
 
@@ -49,38 +83,104 @@ uvx specfact-cli@latest
 pip install -U specfact-cli
 ```
 
-### Bootstrap and IDE Setup
+### Bootstrap
 
 ```bash
-# First run: install official bundles
+# Recommended first run
 specfact init --profile solo-developer
-
-# Alternative bundle selection
-specfact init --install backlog,codebase
-specfact init --install all
-
-# IDE prompt/template setup
-specfact init ide
-specfact init ide --ide cursor
-specfact init ide --ide vscode
 ```
 
-`specfact init ide` discovers prompt resources from installed workflow modules and exports them to your IDE. If module prompt payloads are not installed yet, the CLI uses packaged fallback resources.
-
-### Run Your First Flow
+### Get First Value
 
 ```bash
-# Analyze an existing codebase
+# Analyze a codebase you care about
 specfact code import my-project --repo .
 
-# Snapshot current project state
+# Snapshot the project state for follow-up workflows
 specfact project snapshot --bundle my-project
 
-# Validate external code without modifying source
+# Validate external code without modifying the target repo
 specfact code validate sidecar init my-project /path/to/repo
 specfact code validate sidecar run my-project /path/to/repo
 ```
 
+That path gives you a concrete first win: SpecFact understands your project context and gives you a
+validated starting point instead of jumping straight into blind change work.
+
+### AI IDE Setup
+
+```bash
+specfact init ide
+specfact init ide --ide cursor
+specfact init ide --ide vscode
+```
+
+`specfact init ide` discovers prompt resources from installed workflow modules and exports them to
+your IDE. If module prompt payloads are not installed yet, the CLI uses packaged fallback resources.
+
+## Choose Your Path
+
+### Greenfield and AI-assisted delivery
+
+Use SpecFact as the validation layer around fast-moving implementation work.
+
+Start with:
+- `specfact init --profile solo-developer`
+- `specfact code validate sidecar init <bundle> /path/to/repo`
+- `specfact code validate sidecar run <bundle> /path/to/repo`
+
+### Brownfield and reverse engineering
+
+Use SpecFact to understand an existing system before you change it, then hand that understanding
+into spec-first tools such as OpenSpec or Spec-Kit.
+
+Start with:
+- `specfact code import my-project --repo .`
+- `specfact project snapshot --bundle my-project`
+- `specfact code validate sidecar init my-project /path/to/repo`
+- `specfact code validate sidecar run my-project /path/to/repo`
+
+### Backlog to code alignment
+
+Use SpecFact when the problem is not only code quality, but drift between expectations and delivery.
+Backlog commands require a backlog-enabled profile or installed backlog bundle before the workflow
+commands are available.
+
+Start with:
+- `specfact init --profile backlog-team`
+- `specfact backlog ceremony standup ...`
+- `specfact backlog ceremony refinement ...`
+- `specfact backlog verify-readiness --bundle <bundle-name>`
+
+### Team and policy enforcement
+
+Use SpecFact when multiple developers and AI IDEs need consistent checks and review behavior.
+
+Start with:
+- `specfact backlog verify-readiness --bundle <bundle-name>`
+- `specfact govern ...`
+- CI validation flows that keep the same rules active outside local development
+
+## How do I get started if I want more?
+
+**Next steps**
+
+- **[Core CLI docs](docs/index.md)** for the core runtime, bootstrap, validation, and command topology
+- **[Reference: command topology](docs/reference/commands.md)** for grouped command surfaces
+- **[Canonical modules docs site](https://modules.specfact.io/)** for bundle-deep workflows
+
+## Documentation Topology
+
+`docs.specfact.io` is the canonical starting point for SpecFact.
+
+- Core CLI/runtime/platform documentation remains owned by `specfact-cli`.
+- Module-specific deep docs are canonically owned by `specfact-cli-modules`.
+- The live modules docs site is published at `https://modules.specfact.io/`.
+
+Use this repository's docs for the overall product story, runtime lifecycle, command topology,
+trust model, and getting-started flow. Use the modules docs site when you want deeper workflow,
+adapter, and module-authoring guidance.
+
 ### Migration Note (Flat Commands Removed)
 
 As of `0.40.0`, flat root commands are removed. Use grouped commands:
@@ -120,12 +220,6 @@ For GitHub, replace adapter/org/project with:
 /specfact.01-import my-project --repo .
 ```
 
-**Next steps**
-
-- **[Core CLI docs](docs/index.md)**
-- **[Reference: command topology](docs/reference/commands.md)**
-- **[Canonical modules docs site](https://modules.specfact.io/)**
-
 ---
 
 ## Who It Is For

docs/README.md

@@ -8,10 +8,16 @@ description: High-level index for the SpecFact core CLI docs and canonical modul
 # SpecFact CLI Documentation
 
 This repository owns the **core CLI** documentation set for SpecFact.
-It explains the overall process of using SpecFact CLI, the platform runtime, and how official modules integrate into the grouped command surface.
+Use it as the canonical starting point when a user still needs orientation around what SpecFact is,
+why it exists, what value it provides, and how to get started.
 
-For **module-specific deep functionality**, use the canonical modules docs site at `https://modules.specfact.io/`.
-The canonical modules docs site owns the detailed guides for bundle workflows, adapters, and module authoring.
+SpecFact is the validation and alignment layer for software delivery. The core docs explain the
+product story, runtime lifecycle, bootstrap path, and the handoff into deeper module-owned
+workflows.
+
+For **module-specific deep functionality**, use the canonical modules docs site at
+`https://modules.specfact.io/`. The canonical modules docs site owns the detailed guides for bundle
+workflows, adapters, and module authoring.
 
 ## Core Docs Scope
 
@@ -35,6 +41,10 @@ Use the canonical modules docs site for:
 The canonical modules docs site is currently published at `https://modules.specfact.io/`.
 This docs set keeps release-line overview and handoff content for bundle workflows while the canonical modules docs site carries the deep bundle-specific guidance.
 
+If a modules page is ever used as a first-contact surface, it must explain that `modules.specfact.io`
+is the deeper workflow layer and direct un-oriented users back to `docs.specfact.io` for the core
+product story and fast-start path.
+
 ## Cross-site contract
 
 - [Documentation URL contract (core and modules)](reference/documentation-url-contract.md) — linking rules vs `modules.specfact.io`