BUREAU / Documentation / First 15 minutes

First 15 minutes

From a clean install to a project with a brief, comps, build, QA, and an open circuit.

1. Requirements

• Node.js 20+.
• Git.
• Optional: Playwright + Chromium for visual QA.
• Optional: Figma Desktop/Dev Mode or Figma MCP for variables.
• Optional: ffmpeg and ImageMagick for media.

node --version
git --version
node skill/scripts/doctor.mjs

doctor reports what is available and what will degrade.

2. Install

git clone https://github.com/acf1210/bureau.git
cd bureau

bash installers/install.sh --agent all --scope user --dry-run
bash installers/install.sh --agent all --scope user

Windows:

powershell -ExecutionPolicy Bypass -File installers/install.ps1 -Agent all -Scope user -DryRun
powershell -ExecutionPolicy Bypass -File installers/install.ps1 -Agent all -Scope user

Restart the agent. /bureau should appear.

3. Toolkit dependencies

npm install --no-bin-links
npx playwright install chromium

--no-bin-links is only needed on mounts that do not support symlinks (some SMB shares). On a local disk, npm install is enough.

If Playwright's Chromium cannot download, the script automatically falls back to a system Chromium. You can also point it:

BUREAU_CHROMIUM=/usr/bin/chromium node skill/scripts/visual-audit.mjs ...

4. Create a project

node skill/scripts/new-project.mjs my-site --template kinetic-editorial
cd my-site

Each template is self-contained: HTML, CSS, JS, media, tokens.

5. Fill in the truth

Open BUREAU.md. Replace every TODO:

• specific audience and current alternative;
• offer and sourced proof;
• claims you cannot make;
• mode (PERSUADE, EXPERIENCE, OPERATE, READ);
• performance budget;
• definition of done.

Without this, Gate 0 does not pass. It is not paperwork; it is what stops the project from becoming decoration.

6. Three directions

Ask the agent:

/bureau concept

Or do it manually:

1. Create .bureau/comps/.
2. Produce three comps at the same viewport (1440×900) with real content.
3. Name each direction; write the thesis, signature move, and risk.
4. Score with the matrix in skill/references/02-concept-engine.md.
5. Record the decision in .bureau/comps/decision.md and the blend in .bureau/comps/blend.md.

Without three directions there is no decision — only the first impulse.

7. Build

python3 -m http.server 4173
# or
npx serve .

Build the first viewport as a complete thesis, not a header. Then the whole page.

8. Visual QA

node <bureau>/skill/scripts/visual-audit.mjs http://localhost:4173 \
  --out .bureau/qa \
  --viewports 390x844,768x1024,1440x900,1920x1080 \
  --full --motion

Open the screenshots. The JSON is evidence; the eye is the judge.

9. Open the circuit

Create a score file. Gate 0 example:

{
  "gate": "g0-intake",
  "score": 4.5,
  "notes": "Brief complete; main proof sourced; non-goals explicit.",
  "issues": [],
  "evidence": ["BUREAU.md", ".bureau/config.json"]
}

node <bureau>/skill/scripts/review.mjs --gate g0-intake --scores .bureau/review/g0.json
node <bureau>/skill/scripts/review.mjs --status

The script refuses out-of-order gates, missing evidence, and scores below 3.5.

10. Tribunal

node <bureau>/skill/scripts/review.mjs --final --tribunal .bureau/review/tribunal.json

The Tribunal requires a written statement. The result lands in .bureau/review/scorecard.html.

Project artifacts

BUREAU.md              truth and scope
DESIGN.md              visual contract
MOTION.md              motion grammar
.bureau/
  config.json          mode, budgets, viewports
  comps/               three directions + decision
  evidence/            audits, contrast, type, copy
  qa/                  screenshots + report.json
  review/              state, scores, scorecard

If something breaks

Next: Architecture · Circuit · Commands.