updated concepts

2026-03-02 12:06:47 +05:00
parent 3776747e8a
commit 569bc9e5e2
25 changed files with 828 additions and 351 deletions
@@ -97,6 +97,6 @@ Rules that verify all hyperlinks in the report are valid.

 | # | Category | Check | Depth | Compare Against | Added | Origin |
 |---|----------|-------|-------|-----------------|-------|--------|
-| 8A | Local File Links | Verify all relative file links (e.g. `../.claude/agents/weather.md`) resolve to existing files | exists | local filesystem | 2026-02-28 | File moves (reports/ → best-practice/) broke relative links — must catch future breakage |
+| 8A | Local File Links | Verify all relative file links (e.g. `../.claude/agents/weather-agent.md`) resolve to existing files | exists | local filesystem | 2026-02-28 | File moves (reports/ → best-practice/) broke relative links — must catch future breakage |
 | 8B | External URL Links | Verify all external URLs (e.g. `https://code.claude.com/docs/en/sub-agents`) return valid pages | exists | HTTP response | 2026-02-28 | External docs pages can be restructured or removed — must validate on each run |
 | 8C | Cross-File Reference Links | Verify links to other report files (e.g. `../claude-agent-memory.md`) resolve to existing files | exists | local filesystem | 2026-02-28 | Reports can be moved or renamed — cross-references must stay in sync |
@@ -0,0 +1,46 @@
+# Changelog — README CONCEPTS Section
+
+Tracks drift between the README CONCEPTS table and official Claude Code documentation.
+
+## Status Legend
+
+| Status | Meaning |
+|--------|---------|
+| `COMPLETE (reason)` | Action was taken and resolved successfully |
+| `INVALID (reason)` | Finding was incorrect, not applicable, or intentional |
+| `ON HOLD (reason)` | Action deferred, waiting on external dependency or user decision |
+
+---
+
+## [2026-03-02 11:14 AM PKT] Claude Code v2.1.63
+
+| # | Priority | Type | Action | Status |
+|---|----------|------|--------|--------|
+| 1 | HIGH | Broken URL | Fix Permissions URL from `/iam` to `/permissions` | COMPLETE (URL updated to /permissions) |
+| 2 | HIGH | Missing Concept | Add Agent Teams row to CONCEPTS table | COMPLETE (row added with ~\/\.claude\/teams\/ location) |
+| 3 | HIGH | Missing Concept | Add Keybindings row to CONCEPTS table | COMPLETE (row added with ~\/\.claude\/keybindings\.json location) |
+| 4 | HIGH | Missing Concept | Add Model Configuration row to CONCEPTS table | COMPLETE (row added with \.claude\/settings\.json location) |
+| 5 | HIGH | Missing Concept | Add Auto Memory row to CONCEPTS table | COMPLETE (row added with ~\/\.claude\/projects\/<project>\/memory\/ location) |
+| 6 | HIGH | Stale Anchor | Fix Rules URL anchor from `#modular-rules-with-clauderules` to `#organize-rules-with-clauderules` | COMPLETE (anchor updated) |
+| 7 | MED | Missing Concept | Add Checkpointing row to CONCEPTS table | COMPLETE (row added with automatic git-based location) |
+| 8 | MED | Missing Concept | Add Status Line row to CONCEPTS table | COMPLETE (row added with ~\/\.claude\/settings\.json location) |
+| 9 | MED | Missing Concept | Add Remote Control row to CONCEPTS table | COMPLETE (row added with CLI \/ claude\.ai location) |
+| 10 | MED | Missing Concept | Add Fast Mode row to CONCEPTS table | COMPLETE (row added with \.claude\/settings\.json location) |
+| 11 | MED | Missing Concept | Add Headless Mode row to CONCEPTS table | COMPLETE (row added with CLI flag -p location) |
+| 12 | LOW | Changed Description | Update Memory description to mention auto memory | COMPLETE (description and location updated) |
+| 13 | LOW | Changed Location | Update MCP Servers location to include `.mcp.json` | COMPLETE (location updated to include .mcp.json) |
+| 14 | LOW | Missing Badge | Add Implemented badge to Hooks row | COMPLETE (Implemented badge added linking to .claude/hooks/) |
+
+---
+
+## [2026-03-02 11:57 AM PKT] Claude Code v2.1.63
+
+| # | Priority | Type | Action | Status |
+|---|----------|------|--------|--------|
+| 1 | HIGH | Table Consolidation | Consolidate CONCEPTS table from 22 rows to 10 rows — fold related concepts as inline doc links | COMPLETE (22 → 10 rows) |
+| 2 | MED | Merged Concept | Fold Marketplaces into Plugins row as inline link | COMPLETE (linked to /discover-plugins) |
+| 3 | MED | Merged Concept | Fold Agent Teams into Sub-Agents row as inline link | COMPLETE (linked to /agent-teams) |
+| 4 | MED | Merged Concept | Fold Permissions, Model Config, Output Styles, Sandboxing, Keybindings, Status Line, Fast Mode into Settings row as inline links | COMPLETE (7 concepts folded with doc links) |
+| 5 | MED | Merged Concept | Fold Auto Memory and Rules into Memory row as inline links | COMPLETE (linked to /memory and /memory#organize-rules-with-clauderules) |
+| 6 | MED | Merged Concept | Fold Headless Mode into Remote Control row as inline link | COMPLETE (linked to /headless) |
+| 7 | LOW | Reorder | Reorder table by logical grouping: building blocks → extension → config → context → runtime | COMPLETE (grouped by concern, not chronology) |
@@ -0,0 +1,45 @@
+# Verification Checklist — README CONCEPTS Section
+
+Rules for verifying CONCEPTS table accuracy. Each rule is checked during every workflow run.
+
+## Rules
+
+### 1. External URL Liveness
+- **Category**: URL Accuracy
+- **What to check**: Every external URL in the CONCEPTS table (docs links) returns a valid page
+- **Depth**: Fetch each URL and confirm it loads the expected page (not a redirect to wrong page)
+- **Source to compare against**: `https://code.claude.com/docs/llms.txt` for canonical URL list
+- **Date added**: 2026-03-02
+- **Origin**: Permissions URL `/iam` was found to redirect to Authentication page instead of Permissions
+
+### 2. Anchor Fragment Validity
+- **Category**: URL Accuracy
+- **What to check**: Any URL with an anchor fragment (`#section-name`) matches an actual heading on the target page
+- **Depth**: Fetch the page and verify the heading exists with the expected anchor
+- **Source to compare against**: Fetched page content
+- **Date added**: 2026-03-02
+- **Origin**: Rules anchor `#modular-rules-with-clauderules` was stale; section renamed to `#organize-rules-with-clauderules`
+
+### 3. Missing Docs Pages
+- **Category**: Missing Concepts
+- **What to check**: Every page in the official docs index (`llms.txt`) that represents a user-facing feature has a corresponding row in the CONCEPTS table
+- **Depth**: Compare full docs index against CONCEPTS table entries
+- **Source to compare against**: `https://code.claude.com/docs/llms.txt`
+- **Date added**: 2026-03-02
+- **Origin**: Multiple missing concepts found (Agent Teams, Keybindings, Model Configuration, etc.)
+
+### 4. Local Badge Link Validity
+- **Category**: Badge Accuracy
+- **What to check**: Every badge target path in the CONCEPTS table (`best-practice/*.md`, `implementation/*.md`, `.claude/*/`) points to a file or directory that exists
+- **Depth**: Use Read/Glob to verify file existence
+- **Source to compare against**: Local filesystem
+- **Date added**: 2026-03-02
+- **Origin**: Initial checklist creation
+
+### 5. Description Currency
+- **Category**: Description Accuracy
+- **What to check**: Each concept's description accurately reflects the current official docs description
+- **Depth**: Compare README description against the official page's meta description or first paragraph
+- **Source to compare against**: Official docs page content
+- **Date added**: 2026-03-02
+- **Origin**: Memory description missing auto memory; MCP Servers location missing `.mcp.json`