docs: add SQL-first end-to-end tutorial

[mk3008]

Adds the SQL-first end-to-end tutorial and docs navigation for #597.\n\nVerification:\n- pnpm --filter @rawsql-ts/ztd-cli test -- sqlFirstTutorial.docs.test.ts\n- pnpm verify:published-package-mode\n- pnpm verify:customer-consumers

Summary by CodeRabbit

• Documentation

  • Added a new SQL-first End-to-End Tutorial providing step-by-step workflow guidance from schema definition through first passing test
  • Updated navigation and README with cross-references to the tutorial

• Tests

  • Added test suite to validate tutorial integration and documentation consistency

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request introduces a comprehensive SQL-first End-to-End Tutorial across the documentation structure, including a new tutorial guide file, updates to navigation configuration, feature index, README files, and a test suite to validate the tutorial's integration and correctness.

Changes

Cohort / File(s)	Summary
Documentation Setup README.md, docs/.vitepress/config.mts, docs/guide/feature-index.md	Added new Tutorials subsection in root README, created sidebar navigation entry for the SQL-first tutorial, and registered the tutorial in the feature index documentation table.
Tutorial Content docs/guide/sql-first-end-to-end-tutorial.md	New comprehensive tutorial guide documenting the SQL-first workflow from DDL through test, including step-by-step instructions, sample code, artifact listings, and recommended next steps.
CLI Documentation packages/ztd-cli/README.md	Added cross-reference links to the SQL-first End-to-End Tutorial in two locations within the CLI documentation.
Test Coverage packages/ztd-cli/tests/sqlFirstTutorial.docs.test.ts	New test suite validating tutorial integration, including helper functions to normalize file content and verify correct ordering of tutorial elements across README and documentation files.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• fix: clarify init first-success path #604: Makes coordinated changes to SQL-first documentation and test expectations around the DDL→model-gen→test workflow.

Poem

🐰 A tutorial hops into view,
SQL-first from start to finish too!
From DDL to tests so fine,
Each step and guide in perfect line.
Documentation trails we weave with care,
For seekers ready to explore and dare! 📚✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a SQL-first end-to-end tutorial to the documentation, which is the primary focus across all modified files (README, config, new tutorial file, tests).

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/npm-consumer-guards

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/guide/sql-first-end-to-end-tutorial.md (1)

10-12: Minor redundancy in the introduction.

Lines 10-12 repeat similar information about "one table, one SQL asset, one repository seam, and one smoke test." Consider consolidating:

✏️ Suggested consolidation

 It walks the sequence `DDL -> SQL -> ztd-config -> model-gen -> repository wiring -> first test` with one table, one SQL asset, one repository seam, and one smoke test.
 
-It uses one table, one SQL asset, one repository seam, and one smoke test. The sequence stays aligned with the first-success path established by `ztd init`, `ztd-config`, `model-gen`, and `npm run test`.
+The sequence stays aligned with the first-success path established by `ztd init`, `ztd-config`, `model-gen`, and `npm run test`.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/guide/sql-first-end-to-end-tutorial.md` around lines 10 - 12,
Consolidate the repeated sentences describing the tutorial setup by removing the
duplication of "one table, one SQL asset, one repository seam, and one smoke
test" and combining the two lines into a single clear intro sentence that still
conveys the sequence (DDL -> SQL -> ztd-config -> model-gen -> repository wiring
-> first test) and alignment with the first-success path (`ztd init`,
`ztd-config`, `model-gen`, `npm run test`); update the paragraph so it reads
once with both the sequence and the summary of assets/seams/tests to avoid
redundancy.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/guide/sql-first-end-to-end-tutorial.md`:
- Around line 10-12: Consolidate the repeated sentences describing the tutorial
setup by removing the duplication of "one table, one SQL asset, one repository
seam, and one smoke test" and combining the two lines into a single clear intro
sentence that still conveys the sequence (DDL -> SQL -> ztd-config -> model-gen
-> repository wiring -> first test) and alignment with the first-success path
(`ztd init`, `ztd-config`, `model-gen`, `npm run test`); update the paragraph so
it reads once with both the sequence and the summary of assets/seams/tests to
avoid redundancy.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8f320b1b-6ae3-4e86-8d42-e7704cb9dd00

📥 Commits

Reviewing files that changed from the base of the PR and between 285f9b8 and be92095.

📒 Files selected for processing (6)

• README.md
• docs/.vitepress/config.mts
• docs/guide/feature-index.md
• docs/guide/sql-first-end-to-end-tutorial.md
• packages/ztd-cli/README.md
• packages/ztd-cli/tests/sqlFirstTutorial.docs.test.ts