[NathanG-TD]

Brings the skill package back under the 200-file upload limit: 250 → 194 files. Addresses #80.

This is the first part of the simplification pass. The design for the whole pass (options, CI checks against file creep, TOML configuration files, phases) is in docs/simplification-design.md on the docs/80-simplification-design branch, which is being reviewed. The two changes here are the ones that are common sense, A and B1. The rest waits for that review.

A. Keep files an agent never reads out of the package

An install is git archive of a commit, which is also what GitHub's "Download ZIP" gives you. A new .gitattributes marks these export-ignore, so they stay in the repository but leave the package:

• tooling/**/tests/
• .github/
• docs/
• REMAINING_WORK.md
• .gitignore, .gitattributes

The three .gitkeep files in design/ are deleted, since those directories already hold files. The README's install section now says to install from the ZIP (or git archive HEAD) where a file limit applies, because a clone carries everything.

B1. One README per binding, with a section per module and pattern

Each binding kept a README in every module and pattern directory. That was 34 files, a quarter of implementation/, all with the same layout. They are now numbered sections of the platform's README.md:

• The section title includes the design anchor, e.g. ## 4. Semantic module (semantic).
• The sections are in deployment order, and each module or pattern has the same number on every binding: §1 object placement, §2 temporal lifecycle metadata, §3–§8 the modules, §9 validation, §10 access layer, §11 physical storage. Teradata adds §12, the catalogue interface.
• Each section names the directory its templates are in.
• Templates are unchanged and stay where they were. A module or pattern with nothing to render keeps its section and loses its directory: DuckDB's access-layer and every binding's physical-storage.
• The content was moved, not rewritten: headings are one level lower, and relative links are re-pointed to work from the new location.

What changed to match:

• Authoring standard §5: one numbered section per module and pattern, numbered alike on every binding. A template directory exists only where something renders. A new module or pattern adds a section, not a file.
• Design documents: design/README.md, DESIGN_LANGUAGE.md and every module and pattern document's "Implementations" line point at the README section plus the template directory.
• Role files: routes cite sections by number, e.g. implementation/{platform}/README.md §4. verify_skill already checks §N citations on every platform.
• Release index: build_release.py read binding coverage from directories, which would have dropped DuckDB's access layer and physical storage from bindings.json. It now reads the README sections, and release/v2.0.0/bindings.json is unchanged.
• Package test: the per-directory README checks are replaced by a test that requires every module and pattern section on every binding, numbered alike and naming a real design anchor. It also checks that no README remains below the platform root.
• Catalogue: regenerated. The platform catalogues now list only the platform profile, since the per-directory binding documents are gone.

Also fixed: six broken relative links

These were already broken on main:

• examples/README.md linked per-platform ITSD directories that no longer exist. It now links the shared example with each platform's profile.
• Two Teradata example profiles linked design/core/ one level short.
• The Teradata catalogue-interface section and the Alation example linked the amended modules/semantic/03-registry.sql.j2, removed in d183770. They now link its last version in history and say that the registry 2.0 changes are not yet in the build context's DataProductRegistry, which is part of the open port-or-retire decision.

How to test

python -m unittest discover -s tooling/validation/tests
python -m unittest discover -s tooling/bindings/tests
python -m unittest discover -s tooling/release/tests
python tooling/validation/design_lint.py design implementation
python tooling/catalogue/build_catalogue.py --check
python tooling/release/build_release.py --check
python tooling/skill/verify_skill.py --package

Verification

Check	Result
Package (verify_skill.py --package)	194 files, conforms. Before: 250
Validation tests	272 run, pass
Bindings tests	118 run, pass, 96 skipped: the DuckDB, Postgres and Teradata engine tests, with no engine installed locally
Release tests	18 run, pass; release bundle current
Design lint, catalogue check	Clean, current
Relative links	Every link in every tracked .md file resolves, including #section anchors

No template changed (git diff main --stat -- '*.j2' is empty), so rendered SQL is unaffected. CI runs the DuckDB engine tests.

Review points

• Headroom is small. 194 leaves 6 files. Consolidating templates (B2 in the design) is the next step and takes a binding from about 45 files to about 14. Until then, adding files should be avoided.
• A clone still carries everything. export-ignore affects only the ZIP and git archive. If Claude Code installs from a clone and has its own limit, that is open question 1 in the design doc.
• Section numbers are now part of the contract. Role files cite them, and the new package test fails if a section's number differs between bindings.
• Bigger files. The merged READMEs are about 480 lines for DuckDB and Postgres and about 640 for Teradata. Routes cite sections, so an agent can go straight to the one it needs.

Checklist

• Commit messages follow discipline (three commits: package filter, README sections, link fixes)
• No secrets committed
• Tests pass (engine tests skipped locally, as above)
• Documentation updated (authoring standard, design README and documents, role files, platform READMEs, install section)
• No new file types needing .gitignore changes

[earthshiner]

This is a really good initiative.
We must add check to prevent the file count growing larger than the limit again, though.

One other thing, if the readmes become fewer but larger, the agent now has more to read to get the information = more tokens. So we need to add an indexing strategy for the readmes so that the agent can go straight to the content of value without reading the whole readme file.

[NathanG-TD]

We will add a file check/limit test in the next PR. Index changes to large README files (over 100 lines) has been added. Teradata tests have been optimised and now run roughly in 50% of original time.