docs: rename README.md → docs-discoverability-spec.md#37
Merged
Conversation
…SPEC The "README" name was a draft-phase artifact — the doc was a proposal when written. It's now an accepted standard (status: accepted, lifecycle: active) whose primary function is to specify the vocabulary, frontmatter schema, layout rules, and CI gates. By the filename convention the doc itself defines (§7), `*-spec.md` is the correct shape for a "formal specification, grammar, contract" doc. Also matches the sibling-folder pattern in `ai-discoverability/`. Frontmatter changes: - doc_type: [PROPOSAL, DESIGN, PLAN] → [SPEC, DESIGN, PLAN] - former_doc_type + former_filename added (preservation of the draft-phase shape; the spec's §13 retains the full design record) - revisions bumped 0 → 2 (git-derived count after this edit) Tracker (phases-tracker.md) updated: - All anchor links README.md#... → docs-discoverability-spec.md#... - Narrative "README §N" mentions → "spec §N" - Per-repo `docs/README.md` references intentionally left untouched (they refer to the per-repo index files, not the org spec) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 tasks
9 tasks
rafael5
added a commit
that referenced
this pull request
May 11, 2026
…#40) m-dev-tools is fully AI-enabled (Phase 4 MCP server + Phase 5 continuous-enforcement gates all live). The org-landing README's "For AI agents" section pre-dated the MCP server and led with raw tools.json; this PR rewrites that section to lead with the MCP endpoint and points readers at a new, dedicated AI users guide for the full walk-through. Direct catalog access stays documented as the no-MCP fallback. ### profile/README.md — "For AI agents and automated tooling" Rewritten: * Opens with the MCP install (drop-in .mcp.json for any MCP-capable agent — Claude Code / Codex / Continue / ...). * Names the three tools (route_intent / describe / verify) + one-line behaviour summary. * Links to the new users guide for the walk-through. * Direct-catalog path stays as a second-class fallback. Catalog links + the 8-step discovery handshake reference to the architecture doc are surfaced. * Mentions the four Phase-5 enforcement gates (freshness / link-check / license-reconcile / schema-version) so a reader knows the catalog is CI-enforced honest. * Existing manifest-pointer bullets (m-stdlib API + grammar-surface) preserved. ### New: docs/ai-discoverability/ai-users-guide.md A consumer-facing companion to AI-discoverability-architecture.md (which is for framework *extenders*). Sections: 1. What "AI-enabled" means here — three artifacts + thin MCP wrapper + Phase-5 gates that keep them honest. 2. Two install paths — MCP via uvx + .mcp.json drop-in (Path A, recommended); raw catalog URLs (Path B) for clients without MCP support. 3. Example Claude Code session — user prompt → route_intent → describe → manifest fetch → final answer, with the key invariant "agent never guesses, every claim is grounded in a fetched URL". 4. Agent-free shell smoke via examples/claude-code/smoke.sh. 5. The four typed-ID kinds (tool: / module: / cmd: / recipe:) + note that other kinds in the grammar aren't yet handled by describe (file issue if needed). 6. What the agent WILL and WILL NOT do — including the "verify lists, doesn't execute" security stance with a reference to phase4-plan §3 B5 rationale. 7. Troubleshooting — uvx install, .mcp.json placement, server crash on @main, stale verified_on, offline mode. 8. Where to learn more — links to the architecture doc, plan, guide, phase docs, and the m-dev-tools-mcp repo's AGENTS.md. 9. Reporting issues — which repo issue tracker takes what kind of bug. Frontmatter follows the docs-discoverability spec landed in PR #37 (doc_type: [GUIDE]; lifecycle: active; owner: rmrich5; connections: [function]). ### Verified * make check-docs-prose / check-freshness / check-links / check-licenses / check-schema-compat / recipes-check / handshake / validate-catalog — all clean
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/docs-discoverability/README.md→docs/docs-discoverability/docs-discoverability-spec.mdviagit mv(history preserved).README-as-orientation framing), but it's now an accepted standard whose primary role is specifying the vocabulary, frontmatter schema, layout rules, and CI gates. By the filename convention the doc itself defines in §7,*-spec.mdis the right shape for a formal specification.doc_type:[PROPOSAL, DESIGN, PLAN]→[SPEC, DESIGN, PLAN]. PROPOSAL stays preserved informer_doc_type:and the §13 design record.phases-tracker.md) updates: all spec link anchors and narrativeREADME §Nmentions →docs-discoverability-spec.md/spec §N. Per-repodocs/README.mdreferences (which refer to the per-repo index files I added in Phase 0, not the spec) are intentionally untouched.Test plan
git log --follow docs/docs-discoverability/docs-discoverability-spec.mdshows history continuity from the original creation in phase5-D: schema-version policing gate (TDD) #35.phases-tracker.mdresolve when the renamed file lands.make check-docs-prosestill passes.🤖 Generated with Claude Code