Project file structure

A Denote project is a folder on disk with a known shape. Every file is plain text (Markdown or JSON). Every directory has a specific role. This page is the full tree, annotated with what writes each file, what reads it, and whether you can edit it by hand.

The full tree

my-project/
  .git/                         Initialized on first open if missing.
  .gitignore                    Scaffolded if missing, with .denote/ entries appended.
  .claude/
    commands/                   Slash commands Claude Code finds when you type /<name>.
      vision.md
      ontology.md
      architecture.md
      screens.md
      spec.md
  .denote/                      Per-machine Denote state, gitignored.
    CLAUDE.user.md              Snapshot of build-mode CLAUDE.md while design mode is active.
  intelligence/                 Design knowledge the skills reason from.
    knowledge/
      design-systems/           Tokens, governance, shells, surfaces, visual cues
      interaction-design/       IA, patterns, disclosure, workflows
      object-oriented-ux/       Entities, relationships, states, ontology
      philosophy/               Design philosophy
      product-strategy/         Opportunities, competition, metrics
      user-understanding/       JTBD, mental models, research
      visual-design/            Hierarchy, typography, spacing, color
    skills/
      critique/
      design-system-audit/
      flow-mapping/
      ia-audit/
      object-model/
      product-spec/
      visual-critique/
    agents/
      craft-lead.md
      design-builder.md
      design-critic.md
      product-strategist.md
      ux-architect.md
    catalog/                    Generated JSON exports of system-level catalogs.
      template-variants.json
      pattern-library.json
      content-types.json
      shell-patterns.json
      surface-patterns.json
  design/                       Everything Denote's layers author.
    project.json                Product types (which platforms this project targets).
    vision.json
    ontology.json
    architecture.json
    screens.json
    SPEC.md
    skill.md                    Generated design summary Claude Code reads while building.
    sources/                    Reference materials you add. Tracked in git.
    .denote/                    Internal state, gitignored.
      activity.jsonl            Append-only activity log
      source-links.json         Linked-folder pointers (machine-specific paths)
      images/                   Images pasted into the embedded terminal
  CLAUDE.md                     Regenerated on open in design mode (custom rules preserved) or owned by you in build mode.

What each path is for

`.git/`

Every Denote project is a git repository. Denote runs git init on first open if .git/ is missing, because Claude Code uses the git root to locate .claude/commands/.

You're expected to commit the design files. The commit history is the project's design history.

Safe to edit: yes, with standard git tooling.

`.gitignore`

Scaffolded on first open if missing. Denote appends two entries it insists on: design/.denote/ (internal state) and .denote/ (build-mode CLAUDE.md snapshot). If a .gitignore already exists, the missing entries are appended; nothing is removed. The rest of the file is yours.

Safe to edit: yes. Denote only ensures the two .denote/ entries are present.

`.denote/`

Project-root Denote state, separate from design/.denote/. Currently one file:

CLAUDE.user.md — Snapshot of your build-mode CLAUDE.md, written when you toggle from build to design. Restored to CLAUDE.md when you toggle back to build. Deleted after a successful restore.

Only exists while design mode is active. Build mode "consumes" the snapshot on the way in.

Safe to edit: no. Denote owns the snapshot lifecycle. Gitignored because it's per-machine state.

`.claude/commands/`

The five layer skills, scaffolded into the project on every open: vision.md, ontology.md, architecture.md, screens.md, spec.md. These define the prompt instructions Claude Code executes when you type /<name> in the embedded terminal.

Safe to edit: not these five — they're overwritten on every project open, because they encode Denote app behavior, not designer intent. For per-project customization, edit the knowledge under intelligence/ instead. Command files you add under your own names are left alone.

`intelligence/knowledge/`

The reference knowledge the skills read before reasoning. 34 Markdown files organized into 7 categories. Each file is a focused treatment of a single topic.

Safe to edit: yes. Scaffolding only copies files that don't already exist in the project, so your edits are preserved across opens. Edits are project-scoped; they don't leak back into Denote's defaults.

`intelligence/skills/`

Seven reasoning modules: critique, design-system-audit, flow-mapping, ia-audit, object-model, product-spec, visual-critique. Each has its own directory with a SKILL.md and optional supporting files. Reference methodology for commands of your own.

Safe to edit: yes. Same copy-if-missing scaffolding as knowledge/.

`intelligence/agents/`

Five agent definitions for longer-form roles: craft-lead.md, design-builder.md, design-critic.md, product-strategist.md, ux-architect.md.

Safe to edit: yes. Same copy-if-missing scaffolding.

`intelligence/catalog/`

Generated JSON exports of system-level catalogs that skills reference for canonical IDs and metadata:

template-variants.json — the 48-variant catalog (across 20 templates).
pattern-library.json — the 20 templates with metadata.
content-types.json — the 18 chip content types (icons, labels).
shell-patterns.json — the 7 shell patterns.
surface-patterns.json — the overlay and surface patterns.

Safe to edit: no — refreshed from Denote on every project open. To customize the vocabulary, add project knowledge files instead.

`design/`

Everything Denote's layers author.

File	Layer	Written by	Notes
`project.json`	—	Project creation / Settings	`productTypes`: which platforms the project targets
`vision.json`	Vision	`/vision`	Goals, constraints, non-goals, audience, competitive context, open questions, scratchpad
`ontology.json`	Ontology	`/ontology`	Single file: intent + entities (with inline visual cues) + personas + tasks + mental models + priority rules. `/architecture` writes `task.screenTouchpoints[]` back into it.
`architecture.json`	Architecture	`/architecture`	Top-level `screens[]` (levels, per-surface layouts, purposes, rationales) + `edges[]` (typed navigation)
`screens.json`	Screens	`/screens`	Top-level `shells[]` + `compositions[]` (one per page per surface) + `globalOverlays[]`
`SPEC.md`	Spec	`/spec`	Design specification for the implementer. Fully regenerated each run.
`skill.md`	Spec	Denote (auto)	Natural-language summary of the design; regenerates as design files change. Build-mode Claude reads it on every interaction.

Safe to edit: yes for the .json files — every one is human-readable JSON with an enforced schema, and Denote watches the directory, so hand edits render live. Malformed edits are rejected or flagged. SPEC.md and skill.md are generated — hand edits will be overwritten, so capture changes in the relevant layer instead.

`design/sources/`

The reference materials you add — PRDs, research, competitive notes, any file type. Copied into the project and tracked in git so they travel with the folder. Every skill reads them for context; none may write to them. Linked folders (pointers to directories elsewhere on your machine) are recorded in design/.denote/source-links.json rather than copied.

Safe to edit: yes — they're your files. Add and remove freely, from Denote's Sources panel or Finder.

`design/.denote/`

Denote's internal state for the project, gitignored:

activity.jsonl — append-only log of skill runs, file writes, renames, deletions, and warnings. Persists across sessions.
source-links.json — linked-folder pointers (absolute, machine-specific paths).
images/ — images pasted or dropped into the embedded terminal.

Safe to edit: no. Readable, but Denote owns the formats.

`CLAUDE.md`

Project-scoped instructions for Claude Code. Two distinct shapes depending on the project's current mode (controlled by the top-bar mode chip — see Design and Build mode).

Design mode (default). Denote-managed thinking-partner template, regenerated on project open and on every toggle into design mode. First line is the marker . Ends with a ## Custom Rules section that preserves anything you write below it across regenerations.
Build mode. Yours. First line is . The rest is whatever you put there. On first build switch, Denote writes a minimal starter pointing Claude at design/skill.md and design/SPEC.md; subsequent switches restore whatever you last had.

The marker contract. Denote reads the first  comment to determine the project's mode on load. If missing, Denote treats the project as being in design mode and adds the marker on the next regeneration.

Safe to edit:

In design mode, below the ## Custom Rules marker only. Anything above is regenerated; your edits are lost.
In build mode, anywhere. The whole file is yours; Denote snapshots it to .denote/CLAUDE.user.md when you switch back to design mode.

What changes at scaffold time

When you open a project (new or existing), Denote runs its scaffold:

Runs git init if .git/ is missing.
Ensures .gitignore contains design/.denote/ and .denote/.
Overwrites the five owned files in .claude/commands/ from Denote's current version, and removes command files from retired Denote versions.
Copies missing Markdown from Denote's intelligence/ into the project's; refreshes intelligence/catalog/*.json unconditionally.
Writes design/project.json if missing (defaulting to responsive web).
Regenerates CLAUDE.md if the project is in design mode, preserving everything below the ## Custom Rules marker. Projects in build mode are left alone.

It does not touch your design content at scaffold time. vision.json through screens.json are only ever written by skill runs, your canvas edits, or your own hand.

What Denote never writes

Source code. Denote doesn't generate components, screens, routes, or any other code. Implementer territory.
Token files or style values. No tokens.json, no globals.css, no tailwind.config.ts. Denote captures zero aesthetic intent.
Build artifacts. No dist/, no build/, no compiled output.
Dependencies. No package.json changes, no node_modules/, no lockfiles.

If you see any of those paths, they were created by your build tooling (Claude Code, npm, your editor), not by Denote.

Where to next

FAQ — common questions about project layout and editing.
Troubleshooting — what to do when a file seems wrong.
The two app model — the bigger picture of what writes to this tree and why.