Folders

Claude: Treat this document as authoritative.

This document defines where files live and why.

Do not add new top-level folders without updating this file.

Structure

serve.py → Local server: python3 serve.py → http://localhost:2020 (/ redirects to the docs site)
package.json → Design system dependency + sync and docs scripts
DESIGN.md → Design rules (synced from the package; gitignored)
CLAUDE.md → Claude Code development rules (authoritative)
README.md → Project overview, the full repo map, and getting started
PROJECT-INSTRUCTIONS.md → The content system's brain (Claude Project instructions)
PROJECT_BRIEF.md → Project brief and requirements
PROJECT_STATUS.md → Work log for ongoing work
02 Skills/ → The craft systems (how content gets made) - see README.md
03 Assets/ → Decks, PDFs, swipe files - anything not made by hand here
07 Research/ → Source research behind breakdowns
assets/
  css/
    design-system.css → Framework (synced from the package; gitignored)
    theme.css → Brand fonts (the framework ships the studio palette)
    style.css → Project styles (helpers + Idea Studio layout)
  js/
    theme-toggle.js → Dark-mode toggle
    idea-studio.js → Idea Studio wizard logic
    ideas-data.js → Idea Studio content model + idea banks
    copy-script.js → "Copy script" button in the script pages' header
    nav-section-links.js → Makes the sidebar section icons navigate to their overview pages
  fonts/ → Self-hosted web fonts
  icons/ → Favicons, app icons, icons.svg (synced; gitignored)
  images/ → General images and Open Graph images
scripts/
  sync-design-system.js → Postinstall: copies the package artefacts into place
  materialise-content.js→ Pre-build: flattens the docs/ content subfolders into docs pages
  copy-site-assets.js   → Post-build: copies the project CSS/JS into docs/site/assets/
templates/ → Page and component boilerplate
docs/ → Documentation sources, content sources + generated site
  idea-studio.md → Idea Studio: the interactive workflow tool (raw HTML in markdown)
  foundation/ → Strategy and reference → the site's Content strategy section
  scripts/ → Every finished script (_archive/ holds superseded drafts)
  series/ → The content series, one file per series
  ideas/ → Raw idea capture (idea-inbox.md)
  site/ → The generated site - never hand-edit

assets/css/

The three-layer CSS contract. Load order matters - every page links them in this sequence:

1. design-system.css - the framework, synced from @bydefaultstudio/design-system on npm install. Never edited; never committed.
2. theme.css - brand fonts only. The framework ships the studio palette natively; restating colour semantics in :root here silently overrides dark mode (a bug we shipped once - see the file's header comment).
3. style.css - project styles: the dark-mode toggle icon swap, small helpers, and the Idea Studio layout (§4, scoped under .idea-studio).

docs/

• *.md → project documentation sources (edit these; idea-studio.md is the Idea Studio page - raw HTML in markdown, published at site/tools/idea-studio.html)
• foundation/, scripts/, series/, articles/, ideas/ → the content sources (strategy, scripts, series, long-form articles, idea inbox) - see README.md for the map. Series files are named NN Series Name.md, zero-padded, in priority order
• docs.config.js → docs-kit settings: basePath: '/docs/site', brand CSS, footer, description
• _defaults.md → section ordering for the sidebar (Content strategy, Ideas, Scripts, Series, Articles, Tools, Admin)
• strategy-*.md, scripts-*.md, series-*.md, articles-*.md, ideas-*.md → materialised intermediates (gitignored) generated from docs/foundation/, docs/scripts/, docs/series/, docs/articles/, and docs/ideas/ by scripts/materialise-content.js on every build - edit the sources in the subfolders, not these. These five prefixes are reserved: never name an authored docs page scripts-, ideas-, series-, articles-, or strategy-.
• site/ → the generated site - never hand-edit; rebuild with npm run docs:build
  • site/assets/icons/ → docs favicons, kept across rebuilds

The docs engine is the packaged docs-kit run in place from node_modules - there is no vendored generator in this repo. Design system reference documentation lives at bydefault.design, not here: this site documents this project only (plus the scripts and ideas it publishes).

The content folders

The content system - the actual working material of this project - splits between the numbered folders at the repo root (02 Skills/, 03 Assets/, 07 Research/) and the content subfolders under docs/. Internal layout, naming rules, and "where things go" live in README.md at the repo root. Five docs subfolders feed the site directly: docs/scripts/ (one page per script), docs/ideas/ (an overview page from the inbox intro, plus one page per idea - each top-level bullet in idea-inbox.md becomes its own page), docs/series/ (the Series section - one page per series), docs/articles/ (the Articles section - long-form written pieces; the one-sentence synopsis lives in description frontmatter, and the body is the article itself), and docs/foundation/ (the Content Strategy section - the content strategy), materialised on every docs build. Frontmatter in a source file passes through to its page (title, order, author, platform, pillar, role, format; status: draft keeps a page off the site), and script, series, and article pages get an injected metadata table - on series pages it sits below the one-liner, on article pages at the top (a computed word count, an optional destination, and status), and a series' status decides its sidebar group (the Selected / Testing accordions). Script and article pages also carry a copy button in their header ("Copy script" / "Copy article"): it copies the source markdown from the hook down (for articles, the whole piece), so the injected table stays out of the clipboard. _archive/ subfolders are never published.

Notes

Empty folders are tracked using .gitkeep to preserve structure.