docs: getting-started guide + README polish + history-doc renames#50
Merged
Conversation
profile/README.md's Getting started section previously documented a manual pip-based install path. Now that setup.sh is in the org-meta repo (PR #49), make it the preferred install path and split the walkthrough into a dedicated SETUP doc. - profile/README.md: Getting started now leads with the setup.sh one-liner (both review-first and curl-pipe forms) and points at the new doc for the full walkthrough. - docs/guides/m-dev-tools-setup.md (new): SETUP-typed doc covering audience, prerequisites, quick install via setup.sh, manual install via `git clone m-cli && make bootstrap`, what `m doctor` verifies, next steps (TDD walkthrough, project scaffolding, VS Code extensions, MCP server), and troubleshooting. Frontmatter validates clean against docs.schema.json (Phase 1 P1.3 gate). docs/guides/ is a new subdir, the first under the .github repo's docs/ tree to follow the docs-discoverability spec §6 layout convention (SETUP/GUIDE/TUTORIAL/EXPLAINER live in guides/). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three files in docs/history/ were named inconsistently — some with "m-tool" (singular), some with "and" in the filename. Rename to the m-tools-* convention so the rehosted m-tools docs cluster by prefix in directory listings: - gap-analysis-and-remediation-strategy.md → m-tools-gap-analysis-remediation-ydb.md - m-tool-gap-analysis.md → m-tools-gap-analysis.md - m-tooling-tier1.md → m-tools-remediation-tier1.md Also simplifies the long "Archived snapshot. Imported verbatim from …" banner at the top of each file to a single-line "**History**" pointer back to profile/README.md for current state. The full attribution narrative still lives in docs/history/README.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Repo-name-style heading reads as code; "M Developer Tools" is the display title the README is actually about. Renders better on the org landing page where this README is the primary public surface. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…r1 remediation - m-tools-gap-analysis.md: TOC entry for §8 expanded with sub-entries for each tier (Tier 1 — development loop, Tier 2 — quality gates, Tier 3 — maintenance / ecosystem, Tier 4 — specialised), so readers can jump straight to the impact bucket they care about instead of scrolling §8 from the top. - m-tools-remediation-tier1.md: new leading paragraph framing this document as the focused Tier 1 execution plan and linking back to the new `#tier-1--the-development-loop-transformative-impact` anchor in m-tools-gap-analysis. Companion-doc bullet retargeted at the same anchor for a sharper landing than the §8 root. Also repairs the stale-from-rename links inside the file (m-tool-gap- analysis.md → m-tools-gap-analysis.md; gap-analysis-and-remediation- strategy.md → m-tools-gap-analysis-remediation-ydb.md; the end-of- doc marker updated to the new filename). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Why this exists now leads with the 2026 cross-engine gap analysis (linked at both the doc level and the §8 four-tier anchor) and frames m-dev-tools as the focused remediation of Tier 1 — the inner development loop. Drops the "YottaDB-first with IRIS portability at the runtime layer" line; replaced with a clean "source-level → engine-neutral, so IRIS / YottaDB / any future ANSI-compliant engine work equally" framing. - Getting started shrunk from 22 lines to 9. Single link to the Getting started guide (which carries the prerequisites / manual install / verification / troubleshooting detail) and a three-line installer snippet (curl + less + bash). Drops the OS / prereq / delegation prose — it lives in the guide. Drops the no-review curl-pipe form; the review-first path is the only one shown. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- profile/README.md: new section "Example of Modern M Test-Driven Development and M Standard Library" between Getting started and Licensing. Points at the m-cli TDD lifecycle walkthrough as the end-to-end demonstration of every m subcommand + m-stdlib. - setup.sh + docs/guides/m-dev-tools-setup.md: fix the walkthrough filename in their "Next steps" hints. The actual file under m-cli is m-tdd-lifecycle-walkthrough.md, not m-cli-tdd-lifecycle- walkthrough.md. Earlier session typo. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Copies the 785-line end-to-end transcript from m-cli/docs/m-tdd-lifecycle-walkthrough.md into the meta-repo at docs/guides/m-tdd-stdlib-walkthrough.md so the example sits next to the Getting started guide and renders inline on the org landing page. The original under m-cli remains the source of truth for m-cli releases; this in-org copy is for org-level discoverability. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Now that the walkthrough is rehosted at docs/guides/m-tdd-stdlib-walkthrough.md (commit b2a65ae), the README should link there instead of the external m-cli URL — keeps the org landing page self-contained and renders the walkthrough inline. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Prerequisites section duplicated the Getting started guide (75 lines of system-tools + clone + venv + engine-boot + verify steps). Replace with a 5-line pointer at docs/guides/m-dev-tools-setup.md; the walkthrough now opens with "assumes a green m doctor" and goes straight to §0 Scenario. Also trims the doubled `---` separator between the section and §0. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
Nine commits that polish the org landing README, rehost the m-cli TDD walkthrough into the meta-repo, retitle / rename history docs, and add a dedicated SETUP guide for new contributors.
profile/README.md
# m-dev-tools→# M Developer Tools(display title vs repo name).docs/history/m-tools-gap-analysis.mdat both the doc level and the §8 four-tier anchor.docs/guides/ (new subdir)
m-dev-tools-setup.md— fresh SETUP doc covering prerequisites, install viasetup.shor manual,m doctor, next steps, troubleshooting. Validates clean againstdocs.schema.json.m-tdd-stdlib-walkthrough.md— 785-line in-org rehost of the m-cli TDD lifecycle walkthrough. Prerequisites section trimmed in favor of a pointer at the Getting started guide.setup.sh
m-tdd-lifecycle-walkthrough.md, notm-cli-tdd-lifecycle-walkthrough.md(earlier-session typo).docs/history/
m-tools-*convention so the rehosted m-tools docs cluster by prefix:gap-analysis-and-remediation-strategy.md→m-tools-gap-analysis-remediation-ydb.mdm-tool-gap-analysis.md→m-tools-gap-analysis.mdm-tooling-tier1.md→m-tools-remediation-tier1.mdm-tools-gap-analysis.md: TOC §8 expanded with per-tier sub-entries (Tier 1 / Tier 2 / Tier 3 / Tier 4) so each tier can be linked to directly.m-tools-remediation-tier1.md: new leading paragraph framing it as the focused Tier 1 execution plan + retargeted at the new#tier-1anchor inm-tools-gap-analysis.md. Stale rename links inside the file repaired.Test plan
profile/README.mdresolve locallyprofile/README.mdreturn HTTP 200make check-docs(Phase 1 P1.3 validator, warn-only) — new SETUP doc validates clean; walkthrough has the known SMOKE-TEST / missing-lifecycle warnings carried over from m-cli source (not introduced here)🤖 Generated with Claude Code