Folders - @erlenmasson - Social Media

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

index.html → Project homepage (links to the docs site and Idea Studio)
serve.py → Local server: python3 serve.py → http://localhost:2020
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
  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
templates/ → Page and component boilerplate
docs/ → Documentation sources, content sources + generated site
  idea-studio.md → Idea Studio: the interactive pipeline 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:

design-system.css - the framework, synced from @bydefaultstudio/design-system on npm install. Never edited; never committed.
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).
style.css - project styles: the dark-mode toggle icon swap, small helpers, and the Idea Studio layout (§4, scoped under ).

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/, ideas/ → the content sources (strategy, scripts, series, 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, Tools, Admin)
strategy-*.md, scripts-*.md, series-*.md, ideas-*.md → materialised intermediates (gitignored) generated from docs/foundation/, docs/scripts/, docs/series/, and docs/ideas/ by scripts/materialise-content.js on every build - edit the sources in the subfolders, not these. These four prefixes are reserved: never name an authored docs page scripts-, ideas-, series-, 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. Four 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), 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 and series pages get an injected metadata table - on series pages it sits below the one-liner, and a series' status decides its sidebar group (Live / Experiments). _archive/ subfolders are never published.

Notes

Empty folders are tracked using to preserve structure.