feat: consolidate skills into single-per-API with references/ subdirectories

[pyramation]

feat: consolidate skills into single-per-API with references/ subdirectories

Summary

Follow-up to PR #775. Restructures the generated skill output from 486 individual per-entity skill directories into ~8 consolidated skills (one per API), each with entity documentation in a references/ subdirectory.

Before (486 dirs)

skills/
  orm-public-field/SKILL.md
  orm-public-database/SKILL.md
  hooks-admin-app-grant/SKILL.md
  ...  (486 total)

After (8 dirs)

skills/
  orm-public/
    SKILL.md              ← overview with YAML frontmatter + References section
    references/
      field.md            ← entity-specific docs (no frontmatter)
      database.md
      ...
  orm-admin/
    SKILL.md
    references/...
  hooks-public/
    SKILL.md
    references/...
  hooks-admin/
    SKILL.md
    references/...
  ...

Codegen changes

• docs-utils.ts: Added SkillReferenceDefinition interface and buildSkillReference() helper for reference file generation. Updated buildSkillFile() to accept optional referenceNames and emit a ## References section with links.
• orm/docs-generator.ts: Rewrote generateOrmSkills() — emits one orm-{target}/SKILL.md + per-entity reference files in references/.
• hooks-docs-generator.ts: Rewrote generateHooksSkills() — same pattern as ORM.
• cli/docs-generator.ts: Rewrote both generateSkills() (single-target → cli-{target}/ with context/auth/table/op references) and generateMultiTargetSkills() (emits cli-common/ for shared context/auth + cli-{target}/ per target).
• Test snapshots: Updated 15 snapshots, wrote 3 new ones. All 283 tests pass.

Review & Testing Checklist for Human

• Verify reference file format: Open a few skills/*/references/*.md files and confirm they have NO YAML frontmatter (just # Title + content), while skills/*/SKILL.md files DO have ---\nname:\ndescription:\n--- frontmatter.
• Cross-target entity leakage: The orm-public skill's references include entities from the objects target (e.g., freeze-objects.md, get-all-record.md, store.md). This happens because the public GraphQL schema includes objects tables. Confirm this is expected or whether objects entities should only appear in orm-objects.
• Spot-check the References section: Open skills/orm-public/SKILL.md and verify the ## References section at the bottom has working relative links to all reference files (e.g., [field](references/field.md)).
• CLI multi-target naming: The multi-target CLI generator now produces cli-common/ (shared context/auth) + cli-{target}/ per target. Confirm this naming convention is acceptable.
• Regeneration determinism: Run cd sdk/constructive-sdk && npx tsx scripts/generate-sdk.ts && cd ../constructive-react && npx tsx scripts/generate-react.ts locally — there should be no diff after re-running.

Notes

• The 2 test suite failures (schema-only.test.ts, expand-targets.test.ts) are pre-existing pgsql-seed module resolution issues, unrelated to this PR.
• The full workspace pnpm build has a pre-existing failure in pgsql-client. The codegen package builds cleanly after running cd postgres/pgsql-seed && pnpm build first.
• Reference files intentionally lack YAML frontmatter per Agent Skills conventions — they're documentation, not standalone skills.

Link to Devin Session: https://app.devin.ai/sessions/56210b5075d14c03abb8d475e781b23e
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring