3d-resources CLAUDE.md

3d_resources — project rules

project.md (MANDATORY)

Read project.md at the start of every session. It is the master guide: filesystem map, data model, build pipeline, rules, pending tasks, design style. Treat it as authoritative when any other doc disagrees.

Update project.md after every change. If filesystem layout, rules, goals, vocab, build steps, design conventions, or pending tasks shift, edit project.md in the same change. Stale project.md is a bug.

Controlled vocabulary (entry tags)

Source of truth: schema/vocab.yml + schema/entry.schema.json.

Rule: When adding/editing entries, only use values that already exist in the vocab for these tag groups:

• license (closed enum)
• entry_type (closed enum)
• tags.workflow (closed enum)
• tags.output (closed enum)
• tags.platform (closed enum)
• tags.skill (closed enum)

tags.tech is freeform but curated — prefer existing values; new ones produce warnings, not errors.

Never invent new values for closed enums. If an entry seems to need one (e.g. product-design, print, visionos, tracking, rotoscoping), do NOT add it silently to vocab.yml or entry.schema.json. Instead:

1. Map to the closest existing value (e.g. product-design → product-viz, tracking/rotoscoping → compositing), OR drop the tag if no good fit.
2. Ask the user if a genuinely new category is needed before extending the vocab.

CI runs node scripts/validate.js — closed-enum violations exit 1 and block merge.

Validation

Run node scripts/validate.js after any data edit. Must show ✓ Validation passed. before commit.

Writing style (user-facing text)

Applies to: data/**/*.yml (descriptions, titles, readme_tags), template strings in scripts/render.js, scripts/build-html.js, scripts/build-section-pages.js, scripts/build-feed.js, scripts/build-llms-txt.js, scripts/build-og-images.js, and any other surface a site visitor reads.

Rules:

1. No em-dashes (—). Ever. In titles, use : . In prose, use . (period + capitalize next word) or , depending on context. The OG-image splitter (build-og-images.js) keys on : for two-line layout — don't reintroduce em-dashes.
2. No AI tells. Banned words/phrases: comprehensive, robust, powerful, seamless(ly), leverage(s/d) (use "use"), utilize(s/d/ing) (use "use"), cutting-edge, state-of-the-art, the ultimate, game-changing, unleash. Banned trailing phrases: and more, and beyond, and so much more.
3. No marketing adjective stacks ("fast, free, and powerful"). One concrete attribute beats three vague ones.
4. Caveman lite for descriptions. Terse, factual, 1 sentence preferred. State what it is and what it does. Drop hype.
5. Internal docs/memory/CLAUDE.md/comments are exempt. Em-dashes and informal hedging are fine there.