docs(cli): center query-unit guidance in scaffold docs

[mk3008]

Closes #601

Summary:

• Promote 1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO as the primary query-unit rule in repo and scaffold docs.
• Keep tables/views as lower-level implementation examples.
• Add a lightweight docs regression test and refresh init expectations for the new wording.

Verification:

• pnpm --filter @rawsql-ts/ztd-cli test -- directoryFinding.docs.test.ts init.command.test.ts -u
• pnpm --filter @rawsql-ts/ztd-cli test -- sqlFirstTutorial.docs.test.ts
• pnpm lint
• pnpm build

Summary by CodeRabbit

• Documentation

  • Updated guidance to establish a unified query-unit structure: one SQL file paired with one QuerySpec, repository entrypoint, and DTO.
  • Clarified query-unit principles across project templates and agent policies.
  • Repositioned table and view repositories as lower-level examples within the query-unit framework.

• Tests

  • Added comprehensive validation tests to ensure consistent messaging of query-unit guidance across documentation.
  • Enhanced test coverage to verify query-unit alignment in generated scaffolds.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR establishes a core architectural principle across documentation and policy: 1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO as the fundamental unit. Updates include a changeset file, modifications to root and template READMEs, policy documentation (AGENTS.md) across multiple repository paths, and new/updated tests to verify documentation consistency.

Changes

Cohort / File(s)	Summary
Changeset & Root Documentation .changeset/quiet-badgers-smile.md, README.md	Added changeset for patch release and updated root README to introduce the per-query-unit guideline (1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO) under "Intent and Procedure".
Template README Files packages/ztd-cli/templates/README.md, packages/ztd-cli/templates/README.webapi.md	Updated scaffold documentation to reflect query-unit principle, reframing src/sql and persistence assets as human-owned sources for individual query units; added guidance to treat tables/views as lower-level implementation examples.
Catalog Policy packages/ztd-cli/templates/src/catalog/AGENTS.md	Added requirement that each catalog spec must align with 1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO.
Persistence & Repository Policy packages/ztd-cli/templates/src/infrastructure/persistence/AGENTS.md, packages/ztd-cli/templates/src/infrastructure/persistence/repositories/AGENTS.md, packages/ztd-cli/templates/src/infrastructure/persistence/repositories/tables/AGENTS.md, packages/ztd-cli/templates/src/infrastructure/persistence/repositories/views/AGENTS.md	Added alignment requirements for query-unit principle across persistence layer; expanded package scope descriptions and added test coverage, error handling, and CUD behavior rules for table and view repositories.
Non-WebAPI Repository Policy packages/ztd-cli/templates/src/repositories/AGENTS.md, packages/ztd-cli/templates/src/repositories/tables/AGENTS.md, packages/ztd-cli/templates/src/repositories/views/AGENTS.md	Updated repository policy to enforce query-unit alignment (1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO); reframed tables/views as lower-level examples; added requirements for test coverage, telemetry support, and CUD behavior; added prohibitions on business rule embedding and SQL workarounds.
Documentation & Test Validation packages/ztd-cli/tests/directoryFinding.docs.test.ts, packages/ztd-cli/tests/init.command.test.ts	Created new test file to validate consistent phrasing of query-unit rule across READMEs and AGENTS.md files; added assertions in init tests to verify presence of "1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO" in generated README outputs.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• docs: unify AGENTS contracts and standardize design notes #454 — Both modify template documentation and AGENTS.md policy files to standardize repository guidance and query-unit design principles across the scaffold.
• feat(cli): add QuerySpec-first scaffold sample #609 — Both update ztd-cli scaffolding templates and init tests to promote query-unit-first workflow and QuerySpec alignment within repository guidance.
• docs(policy): add intent and procedure guidance #613 — Both modify repository policy documentation (AGENTS.md and README) to add procedural guidance and introduce tests for documentation verification and consistency.

Poem

🐰 A query, a spec, a repo so neat,
One DTO makes the unit complete!
No more confusion 'tween read and write—
The rabbit hops left, the rabbit hops right! 🎯
One principle shines with crystalline might!

🚥 Pre-merge checks | ✅ 4 | ❌ 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 (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'docs(cli): center query-unit guidance in scaffold docs' directly summarizes the main change: centering the 1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO query-unit guidance throughout scaffold documentation.
Linked Issues check	✅ Passed	The PR comprehensively implements all coding-related objectives from issue #601: formalizing the 1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO policy across documentation, adding regression tests (directoryFinding.docs.test.ts), updating init test expectations, and reflecting the new guidance throughout AGENTS.md files and READMEs.
Out of Scope Changes check	✅ Passed	All changes are within scope: documentation updates promote the query-unit rule, test additions verify consistent guidance, and init expectations are refreshed to match the new wording—all aligned with issue #601 objectives.

_{✏️ 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)

packages/ztd-cli/templates/src/repositories/views/AGENTS.md (1)

7-7: Consider linking to parent policy instead of restating it verbatim.

Restating the parent query-unit rule here can drift over time; a reference-only phrasing would keep this file focused on directory-local deltas.

Based on learnings: "Keep directory-local deltas in child AGENTS.md files; avoid restating parent rules in child files."

🤖 Prompt for AI Agents

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

In `@packages/ztd-cli/templates/src/repositories/views/AGENTS.md` at line 7,
Remove the verbatim restatement "This subtree MUST stay aligned with the parent
query-unit rule: 1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO."
from AGENTS.md and replace it with a short reference to the parent policy (e.g.,
"See parent query-unit rule for repository structure; keep only directory-local
deltas here.") so the file links to the canonical rule instead of duplicating it
and leaves this doc focused on local exceptions.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In `@packages/ztd-cli/templates/src/repositories/views/AGENTS.md`:
- Line 7: Remove the verbatim restatement "This subtree MUST stay aligned with
the parent query-unit rule: 1 SQL file / 1 QuerySpec / 1 repository entrypoint /
1 DTO." from AGENTS.md and replace it with a short reference to the parent
policy (e.g., "See parent query-unit rule for repository structure; keep only
directory-local deltas here.") so the file links to the canonical rule instead
of duplicating it and leaves this doc focused on local exceptions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: be1c92a4-1c5e-43f7-bbe0-e8ce83f97fa5

📥 Commits

Reviewing files that changed from the base of the PR and between b139582 and 33b300c.

📒 Files selected for processing (14)

• .changeset/quiet-badgers-smile.md
• README.md
• packages/ztd-cli/templates/README.md
• packages/ztd-cli/templates/README.webapi.md
• packages/ztd-cli/templates/src/catalog/AGENTS.md
• packages/ztd-cli/templates/src/infrastructure/persistence/AGENTS.md
• packages/ztd-cli/templates/src/infrastructure/persistence/repositories/AGENTS.md
• packages/ztd-cli/templates/src/infrastructure/persistence/repositories/tables/AGENTS.md
• packages/ztd-cli/templates/src/infrastructure/persistence/repositories/views/AGENTS.md
• packages/ztd-cli/templates/src/repositories/AGENTS.md
• packages/ztd-cli/templates/src/repositories/tables/AGENTS.md
• packages/ztd-cli/templates/src/repositories/views/AGENTS.md
• packages/ztd-cli/tests/directoryFinding.docs.test.ts
• packages/ztd-cli/tests/init.command.test.ts