docs(help): regenerate 10 stale .help features (incl. q39 staleness reference) (#95)

Key-gated handoff item (a) from specs/rag-gate-accuracy-baseline
task 7: the staleness-and-maintenance reference was generated
2026-04-26 pre-refactor and documented only stale_count; it now
covers the refactored StalenessReport (stale_docs et al).

Regenerated all 10 stale-by-source-hash features (30 templates)
with polish + soft fact-check on the fable-5 premium tier
(server-side fallback beta), faithfulness judge ~$0.30.

Author: silversurfer562

.help/templates/bootstrap/concept.md

@@ -1,39 +1,46 @@
 ---
 type: concept
+name: bootstrap-concept
 feature: bootstrap
 depth: concept
-generated_at: 2026-04-14T16:08:15.813184+00:00
-source_hash: 747d4d8b3e41bb5a6d7a534fb1402fcfcda15486e7b1994427f88a2f71907ebf
+generated_at: 2026-07-10T13:07:32.382854+00:00
+source_hash: 40cd7c5eca29231d1a865aa04654239348b46aed8c204904aacc473fc810affe
 status: generated
+scaffold_hash: 86c6577f7fd5f4575d4b8c7ef0c1fb4ae3ef232e9436313a11797aea1ba12888
 ---
 
 # Bootstrap
 
-Bootstrap automatically discovers features in a codebase by scanning directory structures and file patterns, then generates an initial feature manifest.
+Bootstrap scans an existing project and proposes an initial feature manifest, so you don't have to write one from scratch. Instead of listing every feature by hand, you run a scan, review the proposals, and convert the ones you accept into a manifest.
 
-## Discovery process
+## How it works
 
-The scanner examines your project's file system to identify potential features based on:
+The scan-and-convert flow has two steps, each backed by one public function:
 
-- **Entry points** — Files like `main.py`, `app.py`, `cli.py`, `server.py` that typically contain application logic
-- **Configuration patterns** — Directories and files containing "config", "settings", or "conf" in their names
-- **Directory structure** — Organized code folders that suggest distinct functionality
+1. **`scan_project(project_root)`** walks the project's directory structure and Python package layout and returns a list of `ProposedFeature` objects — one per feature it thinks it found. The scanner skips noise directories such as `.git`, `__pycache__`, `.venv`, and `node_modules`, and it uses signals like entry-point filenames (for example `main.py`, `cli.py`, `server.py`) and configuration naming patterns (`config`, `settings`, `conf`) to decide what looks like a feature.
+2. **`proposals_to_manifest(proposals)`** takes the proposals you've accepted and converts them into a `FeatureManifest`, the structure the rest of the system consumes.
 
-The scanner skips common directories that don't contain feature code, such as `.git`, `__pycache__`, `node_modules`, and virtual environments.
+Each `ProposedFeature` carries enough information for you to judge it before accepting:
 
-## Feature proposals
+| Field | What it tells you |
+|---|---|
+| `name` | The proposed feature name |
+| `description` | What the scanner thinks the feature does |
+| `files` | The source files grouped under this feature |
+| `tags` | Searchable tags suggested for the feature |
+| `confidence` | How sure the scanner is (defaults to `medium`) |
+| `reason` | Why the scanner proposed this feature |
 
-Each discovered feature becomes a `ProposedFeature` with these attributes:
+The `confidence` and `reason` fields exist because scanning is heuristic: the scanner explains its guesses so you can accept, edit, or discard each proposal rather than trusting the output blindly.
 
-- **name** — Derived from directory or file names
-- **description** — Generated based on the context where the feature was found
-- **files** — List of relevant source files associated with the feature
-- **tags** — Categorization labels to help organize features
-- **confidence** — Assessment of how certain the scanner is about the feature (defaults to 'medium')
-- **reason** — Explanation of why this was identified as a feature
+## What connects to it
 
-## Manifest generation
+Bootstrap sits at the front of the setup pipeline: it produces the manifest that scanning and generation later depend on. The rest of the codebase interacts with it through these interfaces:
 
-After scanning, you can convert the feature proposals into a structured `FeatureManifest` using `proposals_to_manifest()`. This creates the foundation for documentation generation and project analysis workflows.
+| Interface | Purpose | File |
+|-----------|---------|------|
+| `scan_project` | Scan a project and propose features | `src/attune_author/bootstrap.py` |
+| `proposals_to_manifest` | Convert accepted proposals to a `FeatureManifest` | `src/attune_author/bootstrap.py` |
+| `ProposedFeature` | A feature discovered by scanning | `src/attune_author/bootstrap.py` |
 
-The bootstrap process gives you a starting point that you can refine by accepting, rejecting, or modifying the proposed features before generating your final documentation.
+A useful mental model: bootstrap is the one-time (or occasional) step that turns a raw project tree into structured proposals, and `FeatureManifest` is the handoff point where its job ends and the rest of the system takes over.

.help/templates/bootstrap/reference.md

@@ -1,44 +1,74 @@
 ---
 type: reference
+name: bootstrap-reference
 feature: bootstrap
 depth: reference
-generated_at: 2026-04-14T16:08:35.223900+00:00
-source_hash: 747d4d8b3e41bb5a6d7a534fb1402fcfcda15486e7b1994427f88a2f71907ebf
+generated_at: 2026-07-10T13:07:32.401338+00:00
+source_hash: 40cd7c5eca29231d1a865aa04654239348b46aed8c204904aacc473fc810affe
 status: generated
+scaffold_hash: 04376ece60b306ed2326639b284d6f17a8ea83d0455ee27fd1c9ca0edf713c11
 ---
 
 # Bootstrap reference
 
-Scan projects and generate feature manifests from discovered code patterns.
+Scan a project directory to propose features and convert accepted proposals into an initial feature manifest.
+
+## Functions
+
+| Function | Parameters | Returns | Description | File |
+|----------|------------|---------|-------------|------|
+| `scan_project` | `project_root: str \| Path` | `list[ProposedFeature]` | Scans a project and proposes features from its directory structure. | `src/attune_author/bootstrap.py` |
+| `proposals_to_manifest` | `proposals: list[ProposedFeature]` | `FeatureManifest` | Converts accepted proposals to a `FeatureManifest`. | `src/attune_author/bootstrap.py` |
 
 ## Classes
 
-| Class | Description |
-|-------|-------------|
-| `ProposedFeature` | A feature discovered by scanning |
+| Class | Description | File |
+|-------|-------------|------|
+| `ProposedFeature` | A feature discovered by scanning. | `src/attune_author/bootstrap.py` |
 
 ### ProposedFeature fields
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `name` | `str` | | Feature name |
-| `description` | `str` | | Human-readable description |
-| `files` | `list[str]` | `[]` | Associated file paths |
-| `tags` | `list[str]` | `[]` | Classification tags |
-| `confidence` | `str` | `'medium'` | Detection confidence level |
-| `reason` | `str` | `''` | Why this feature was proposed |
-
-## Functions
+`ProposedFeature` is a dataclass.
 
-| Function | Parameters | Returns | Description |
-|----------|------------|---------|-------------|
-| `scan_project` | `project_root: str \| Path` | `list[ProposedFeature]` | Scan a project and propose features |
-| `proposals_to_manifest` | `proposals: list[ProposedFeature]` | `FeatureManifest` | Convert accepted proposals to a FeatureManifest |
+| Field | Type | Default |
+|-------|------|---------|
+| `name` | `str` | — |
+| `description` | `str` | — |
+| `files` | `list[str]` | `field(default_factory=list)` |
+| `tags` | `list[str]` | `field(default_factory=list)` |
+| `confidence` | `str` | `'medium'` |
+| `reason` | `str` | `''` |
 
 ## Constants
 
+These module constants control what the scanner skips and recognizes.
+
 | Constant | Values | Description |
 |----------|--------|-------------|
-| `_SKIP_DIRS` | `'.git'`, `'.github'`, `'.help'`, `'.claude'`, `'.agents'`, `'__pycache__'`, `'.mypy_cache'`, `'.pytest_cache'`, `'.ruff_cache'`, `'.tox'`, `'.venv'`, `'venv'`, `'env'`, `'node_modules'`, `'dist'`, `'build'`, `'.egg-info'`, `'htmlcov'`, `'site'` | Directories to skip during scanning |
-| `_ENTRY_POINT_NAMES` | `'main.py'`, `'app.py'`, `'cli.py'`, `'server.py'`, `'manage.py'`, `'wsgi.py'`, `'asgi.py'`, `'index.ts'`, `'index.js'`, `'main.go'`, `'main.rs'` | Common application entry point filenames |
-| `_CONFIG_PATTERNS` | `'config'`, `'settings'`, `'conf'` | Filename patterns for configuration files |
+| `_SKIP_DIRS` | `'.git'`, `'.github'`, `'.help'`, `'.claude'`, `'.agents'`, `'__pycache__'`, `'.mypy_cache'`, `'.pytest_cache'`, `'.ruff_cache'`, `'.tox'`, `'.venv'`, `'venv'`, `'env'`, `'node_modules'`, `'dist'`, `'build'`, `'.egg-info'`, `'htmlcov'`, `'site'` | Directories the scan skips. |
+| `_ENTRY_POINT_NAMES` | `'main.py'`, `'app.py'`, `'cli.py'`, `'server.py'`, `'manage.py'`, `'wsgi.py'`, `'asgi.py'`, `'index.ts'`, `'index.js'`, `'main.go'`, `'main.rs'` | Filenames recognized as project entry points. |
+| `_CONFIG_PATTERNS` | `'config'`, `'settings'`, `'conf'` | Name patterns recognized as configuration files. |
+
+## Source files
+
+- `src/attune_author/bootstrap.py`
+
+## Tags
+
+`setup`, `scanning`, `manifest`
+## Faithfulness review
+
+> Auto-generated by attune-author faithfulness judge. Score 0.83 fell below the configured threshold of 0.95. Review unsupported claims and either fix the source code or fix this doc.
+
+**Score:** 0.83 (supported: 19, unsupported: 4)
+
+### Unsupported claims
+
+- The bootstrap reference was generated on 2026-07-10T13:07:32.401338+00:00
+- The source_hash is 40cd7c5eca29231d1a865aa04654239348b46aed8c204904aacc473fc810affe
+- The scaffold_hash is 04376ece60b306ed2326639b284d6f17a8ea83d0455ee27fd1c9ca0edf713c11
+- The tags are 'setup', 'scanning', 'manifest'
+
+### Reasoning
+
+The answer is primarily a reference documentation table extracted directly from the source code and docstrings provided in the passages. Nearly all technical claims about function signatures, parameter types, return types, dataclass fields, and constant values are explicitly stated in the code or docstrings. However, the generated metadata (generated_at timestamp, source_hash, scaffold_hash) and the tags listed at the bottom are not mentioned in the retrieved passages and appear to be document metadata added during generation rather than factual claims about the code itself.

.help/templates/bootstrap/task.md

@@ -1,62 +1,63 @@
 ---
 type: task
+name: bootstrap-task
 feature: bootstrap
 depth: task
-generated_at: 2026-04-14T16:08:25.609534+00:00
-source_hash: 747d4d8b3e41bb5a6d7a534fb1402fcfcda15486e7b1994427f88a2f71907ebf
+generated_at: 2026-07-10T13:07:32.393353+00:00
+source_hash: 40cd7c5eca29231d1a865aa04654239348b46aed8c204904aacc473fc810affe
 status: generated
+scaffold_hash: 1e565108f805b114bd830574e405d1c6d731937c97b5752702b3888cfe225f1c
 ---
 
 # Work with bootstrap
 
-Use bootstrap when you need to automatically generate a feature manifest by scanning an existing project's directory structure and code organization.
+Use bootstrap when you're starting help authoring on an existing project and want a proposed features manifest generated from the project's directory structure instead of writing one by hand.
 
 ## Prerequisites
 
 - Access to the project source code
-- Python environment with the bootstrap module available
+- Familiarity with `src/attune_author/bootstrap.py` and the two-stage flow: scan first, then convert accepted proposals to a manifest
 
-## Scan a project for features
+## Steps
 
-1. **Import the bootstrap module:**
-   ```python
-   from attune_author.bootstrap import scan_project
-   ```
+1. **Trace the scan-to-manifest pipeline.**
+   Read the two public functions in `src/attune_author/bootstrap.py`:
+   - `scan_project(project_root)` walks the project and returns a `list[ProposedFeature]`. It skips noise directories such as `.git`, `__pycache__`, `.venv`, and `node_modules`, and recognizes entry-point files like `main.py`, `cli.py`, and `index.ts`.
+   - `proposals_to_manifest(proposals)` converts the accepted proposals into a `FeatureManifest`.
 
-2. **Run the project scan:**
-   ```python
-   proposals = scan_project("/path/to/your/project")
-   ```
-   The scanner examines your project structure, identifies entry points like `main.py` or `app.py`, and skips common directories like `.git`, `__pycache__`, and `node_modules`.
+2. **Pick the function that owns your change.**
+   Modify `scan_project()` if your change affects how features are discovered — for example, which directories are skipped or how confidence is assigned. Modify `proposals_to_manifest()` if your change affects how accepted proposals become manifest entries.
 
-3. **Review the proposed features:**
-   Each `ProposedFeature` includes:
-   - `name`: The feature identifier
-   - `description`: What the feature does
-   - `files`: Associated source files
-   - `confidence`: Scanner's certainty level
-   - `reason`: Why this feature was proposed
+3. **Edit the code and keep the `ProposedFeature` contract intact.**
+   `ProposedFeature` carries `name`, `description`, `files`, `tags`, `confidence` (defaults to `'medium'`), and `reason`. If your change adds or reinterprets scan output, populate `reason` so users can see why the feature was proposed, and set `confidence` to reflect how strong the signal is.
 
-## Convert proposals to manifest
+4. **Run the bootstrap tests.**
+   Run `pytest -k "bootstrap"` to catch regressions before they reach other developers.
 
-1. **Filter proposals as needed:**
-   Review the confidence levels and reasons to accept or reject proposals.
+## Verify the change
 
-2. **Generate the manifest:**
-   ```python
-   from attune_author.bootstrap import proposals_to_manifest
-   manifest = proposals_to_manifest(accepted_proposals)
-   ```
+Run `scan_project()` against a sample project root and confirm:
 
-3. **Verify the output:**
-   The resulting `FeatureManifest` should contain only the features you want to include in your project documentation.
+- It returns a `list[ProposedFeature]` with the fields you expect populated.
+- No proposals reference files inside skipped directories such as `.venv` or `__pycache__`.
+- Passing the proposals to `proposals_to_manifest()` produces a `FeatureManifest` without errors.
 
-## Success criteria
-
-- `scan_project()` returns a list of `ProposedFeature` objects
-- Each proposal includes relevant files from your project
-- The generated manifest contains structured feature definitions ready for documentation
+All bootstrap tests pass with `pytest -k "bootstrap"`.
 
 ## Key files
 
-- `src/attune_author/bootstrap.py`
+- `src/attune_author/bootstrap.py` — contains `scan_project()`, `proposals_to_manifest()`, and the `ProposedFeature` dataclass
+## Faithfulness review
+
+> Auto-generated by attune-author faithfulness judge. Score 0.80 fell below the configured threshold of 0.95. Review unsupported claims and either fix the source code or fix this doc.
+
+**Score:** 0.80 (supported: 8, unsupported: 2)
+
+### Unsupported claims
+
+- scan_project() walks the project (the passage says it 'scans' but does not explicitly confirm it uses os.walk-style traversal for the initial phase)
+- Modify scan_project() if your change affects how confidence is assigned (the passage does not explicitly discuss how confidence assignment should guide which function to modify)
+
+### Reasoning
+
+The answer documentation provides guidance on working with the bootstrap module. The retrieved passages directly support the main technical claims: the presence and signatures of scan_project() and proposals_to_manifest(), the structure of ProposedFeature with its documented fields, the skipped directories (matching _SKIP_DIRS), entry-point file names (matching _ENTRY_POINT_NAMES), and the default confidence value. The answer accurately reflects what is in the code. Minor unsupported claims relate to implicit procedural guidance not explicitly stated in the passages (e.g., which function to modify for confidence changes), but these are reasonable inferences from the documented scope of each function and do not constitute significant hallucinations. The documentation is faithful to the underlying implementation.