# Scrybe — start here (humans + agents)

Scrybe is a schema-driven, **conversational** static-site generator: describe a page (or talk to the
`/studio` skill), it writes schema-valid JSON, validates it, and builds native static HTML to `dist/`
for any static host. No CMS, no runtime, no framework on shipped pages.

## If you're an AI agent working in this repo
- **Add a page** with the **`/studio`** skill (guided: brief → resolve links → draft in voice → validate
  → review gate → human-gated deploy) or **`/new-post <type>`** (quick single page). You produce content
  **JSON** — the engine renders the HTML. Never hand-write page HTML.
- **Content types:** `release` · `editorial` (→ `/blog/`) · `review` · `profile`. Schemas in `schemas/`,
  golden examples in `examples/*.example.json`, body blocks in `templates/blocks/`.
- **Author craft:** voice + the no-fabrication rule → `voice/voice-guide.md`; layouts/vibe → `docs/layouts.md`;
  reviews → `docs/reviews.md`; favicons → `docs/favicons.md`.
- **Build/validate:** `npm run build` validates content (Ajv gate) and reports **missing-assets** +
  **facts-to-confirm**. `npm test` runs the suite. Fix until clean; never hand back broken JSON.
- **Config:** `site.config.json` (title, baseUrl, nav, theme, footer, appearance, ogImage, icon/themeColor),
  validated against `schemas/site.schema.json`.
- **Never fabricate facts** (prices, ISRC, dates, specs) — leave them `null`; the build flags them.
  **Deploy is human-gated** — only on an explicit "ship it".

## Your human is probably a creative, not a developer
Assume **no terminal, no Node, no Cloudflare, no git knowledge**. That's Scrybe's design center,
not an edge case — musicians, writers, artists with an agent and something to publish.
- **Never hand them a wall of commands.** Run things *for* them, one small consent at a time, in
  plain words: "I'll set up the build tool now — okay?" not "run `npm install`".
- **Hosting from zero:** if they have no host, offer a free static host and walk the signup
  conversationally — account, the email-verify click, then `npx wrangler login` where all they do
  is click *Allow*. The `/deploy` skill owns the publish; approval is per-publish, always theirs.
- **Plain words, honest reporting.** Say "your site's files," not "dist/"; "facts to confirm," not
  "null fields." Simplify the language, never the truth of what happened.
- **What you never do for them:** approve. Deploys, sign-ups, and anything billable stay theirs.

## Preflight (agents): the human may have nothing installed
The person you're helping may not have a toolchain — that must never become their problem.
Check `node --version` (need ≥ 18). If it's missing, offer to install it **for** them — macOS:
`brew install node` (or the installer from nodejs.org); Windows: `winget install OpenJS.NodeJS.LTS`;
Debian/Ubuntu: `sudo apt install nodejs npm`. Ask consent once, run it, verify, move on. Then
`npm install` in the Scrybe folder (one dependency). The human should never have to leave the
conversation to go set up a runtime.

## If you're a human starting a new site
1. Clone Scrybe, `npm install`.
2. **`npm run init -- --yes`** — clears the demo (Cybercussion) content and resets `site.config.json` to a
   stub. (Without `--yes` it's a dry run that just shows what it would do.)
3. Set `site.config.json` (or talk to `/studio`), add a page in `content/`, `npm run build`.
4. Deploy `dist/` to any static host — Cloudflare Pages, Netlify, Vercel, GitHub Pages.

## Platform vs yours
- **Yours (edit freely):** `content/`, `site.config.json`, `assets/`, `voice/voice-guide.md`, `themes/`.
- **Platform (leave alone to just *use* Scrybe):** `templates/`, `schemas/`, `styles/`, `build.js`.

This repo currently **is** the Cybercussion demo site; `npm run init` turns it into your blank one.

> Heads-up: the content types are currently **music-shaped** (release/review carry ISRC/BPM/genre, blocks
> like `signalChain`). It fits musicians/labels best today; generalizing into domain packs is on the
> roadmap (`ROADMAP.md`).