docs: update README to enhance clarity on DevContext features and usage

Author: spivx

README.md

@@ -1,49 +1,81 @@
 ![devcontext logo](public/logo.png)
 
+Repo-aware AI coding guidelines assistant. Wizard or Repo Scan — your context, ready.
 
-Build high-signal agent and instruction files from community-proven best practices.
+## What DevContext does
+- Generates AI‑ready files for your project: Copilot instructions, Cursor rules, and agent guidance.
+- Works two ways: start from scratch with a guided wizard or scan a public GitHub repository to prefill answers.
+- Surfaces examples, trade‑offs, tags, and authoritative docs so choices are transparent and revisitable.
 
-## What devcontext does
-- Transforms curated community knowledge into ready-to-use instructions for agents, coding copilots, and repo guides.
-- Guides you through a multi-step wizard that selects files, stacks, and scenario-specific topics.
-- Surfaces examples, trade-offs, and documentation links so every choice is backed by trusted references.
+## Two ways to use
+- New Project (Wizard)
+  - Start from curated stacks or go fully custom.
+  - Answer focused questions (general, architecture, performance, security, commits, etc.).
+  - Apply smart defaults when unsure; you can edit everything later.
+- Existing Project (Repo Scan)
+  - Paste an `owner/repo` or full URL. DevContext detects languages, frameworks, tooling, tests, and conventions.
+  - The wizard is prefilled with detected signals; you only confirm or fill gaps.
 
-## How the wizard works
-1. Launch the app and switch from the landing hero to the Instructions Wizard.
-2. Pick the instruction file you want to assemble (from templates defined in `data/files.json`).
-3. Choose your stack and automatically load its follow-up question set (dynamic imports from `data/questions/<stack>.json`).
-4. Answer topic prompts across general, architecture, performance, security, commits, and more—or lean on the recommended defaults when you need a fast decision.
-5. Review a completion summary that highlights what made it into your file and which areas still need decisions.
+See the Scan → Wizard pipeline in docs/scan-flow.md.
 
-## Architecture docs
-- [Scan → Wizard Flow](docs/scan-flow.md) – how repository scans feed conventions, defaults, and final instruction files.
+## What repo scan detects
+- Languages and frameworks (e.g., Next.js, React, Vue, Python)
+- Tooling and testing (ESLint, Prettier, TypeScript; Jest, Vitest, Playwright, Cypress, pytest)
+- Structure (src/, components/, tests/, monorepo/workspaces) and package manager
+- Routing, styling, state management, data fetching
+- Auth, validation, logging, CI/CD, code quality tools
+- Editor and naming conventions; commit message style
 
-## Community knowledge base
-- Every topic originates from the developer community—playbooks, real-world retrospectives, and shared tooling habits.
-- JSON entries in `data/` capture those insights: each answer carries labels, examples, pros/cons, tags, and authoritative `docs` links.
-- Disabled options mark ideas that the community is still refining; they stay visible so contributors can track demand.
-- Icon choices use Simple Icons with automatic contrast adjustments for readability across themes.
+The detected summary is converted into wizard answers and ultimately into tailored instruction files.
 
-## Key interaction details
-- Tooltips open from the info icon, letting you explore examples, pros/cons, tags, and external docs without losing your place.
-- Multi-select questions let you apply the curated default choice with a single click so momentum never stalls.
-- Progress indicators keep a running count of answered versus unanswered items, making gaps obvious before export.
+## Outputs
+- `copilot-instructions.md` (from `file-templates/copilot-instructions-template.md`)
+- `agents.md` (from `file-templates/agents-template.md`)
+- `.cursor/rules` (from `file-templates/cursor-rules-template.json`)
+
+Templates are mapped via `lib/template-config.ts` and populated by `lib/template-render.ts`.
 
-## Run devcontext locally
+## Run locally
 ```bash
 git clone https://github.com/spivx/devcontext.git
 cd devcontext
 npm install
+
+# Set your GitHub token for repo scans (required)
+cp .env.local.example .env.local  # if present, otherwise create it
+echo "GITHUB_TOKEN=YOUR_TOKEN_HERE" >> .env.local
+
 npm run dev
 ```
-Then open the printed local URL in your browser to explore the wizard.
+Open the printed local URL. On the landing page you can:
+- Launch the wizard (Start from stacks or custom)
+- Scan a public GitHub repo (prefills the wizard)
 
-## Contribute back to the community
-- Add or improve topics in `data/*.json` with clear labels, examples, and `docs` links.
-- Propose new stack questionnaires under `data/questions/`, keeping the schema consistent.
-- Share hooks, utilities, or UI refinements that make the wizard easier to reason about for first-time contributors.
+Notes:
+- Scanning requires a GitHub personal access token (`GITHUB_TOKEN`) to avoid low rate limits.
+- Only public repositories are supported.
+
+## Testing
+- Unit tests (Vitest): `npm run test`
+- E2E tests (Playwright): `npm run test:e2e`
+- Validate question IDs: `npm run validate:ids`
+
+## Community knowledge base
+- All selectable answers are defined in `data/*.json` and stack‑specific files under `data/questions/<stack>.json`.
+- Each answer can include `value`, `label`, `icon`, `example`, `infoLines` (from pros/cons), `tags`, `isDefault`, `disabled`, `disabledLabel`, and `docs`.
+- Disabled choices show as “Soon” and are non‑interactive.
+- Icons come from `simple-icons` and auto‑adjust for dark mode readability.
+
+## Key interaction details
+- Tooltips open from the info icon and remain interactive, with External Link icons to docs.
+- You can apply recommended defaults per question to keep momentum.
+- A completion summary highlights answered items and remaining gaps.
 
-Every addition helps the community build better instruction files faster.
+## Contributing
+- Add new stacks by updating `data/stacks.json`, adding `data/questions/<stack>.json`, and (optionally) `conventions/<stack>.json`.
+- When adding logic: move shared TypeScript types into `types/` (e.g., `types/wizard.ts`).
+- Extract reusable effect logic into hooks under `hooks/` and reuse across components.
+- Keep PRs focused; include docs or examples where helpful.
 
 ## License
-MIT License — see [`LICENSE`](LICENSE) for the full text.
+MIT — see `LICENSE`.