# Scrybe → v1 roadmap

Synthesized from a 4-lens audit (SEO · AI/LLM · social cards · distribution). Goal: bundle Scrybe so
people build their own site by **talking to an agent + the skills** — an AI-native WordPress
alternative. The *engine* is v1-quality (101 tests, clean output); the *product wrapper* is ~v0.

## Decide first (two calls that shape everything below)
- [x] **Positioning — DECIDED (2026-06-22): general-purpose** — "Scrybe: any site, by conversation."
  Music types (release/review schemas, `signalChain`/`abCompare` blocks, producer voice, `facts.js`
  isrc/bpm) become an **optional pack**. Backlog (P1/P2 product): generalize the demo content, write an
  "add/rename a content type" guide, factor the music specifics into a pack. *(The P0 web table-stakes
  below are positioning-agnostic — building those first.)*
- [ ] **Platform vs site model.** The repo *is* the Cybercussion site. Choose: split engine
  (`@scrybe/core`) from an example site, **or** keep one repo where `content/` + `site.config.json`
  are the only "yours" surface, with a removable `--demo`.

---

## P0 — blocks v1

### Product / distribution
- [ ] **Scaffold / clean start** — `npx create-scrybe` (or a template repo): empty `content/`, stub
  `site.config.json`, starter voice guide, engine intact, **zero Cybercussion**. (`package.json` `bin`.)
  *Today a stranger must clone Cybercussion and gut it by hand — the single biggest blocker.*
- [ ] **Agent "start here"** — a top-level `SCRYBE.md` (or a Scrybe section in `AGENTS.md`, which is
  currently 100% Arc): "you're in a Scrybe site; add pages via `/studio` or `/new-post`; types are…;
  build with `npm run build`." A fresh agent learns nothing about authoring today.
- [ ] **LICENSE** — add one (MIT) + `package.json` `"license"`. Legally unusable without it.
- [ ] **Fix `package-lock.json`** — still named `schema-html-templates`; `npm install` to regenerate.

### Web table-stakes (mostly `layout.js` + `templates/jsonld/*` + `build.js` + `site.config`)
- [ ] **og:image fallback chain** — most pages (home, indexes, profiles, posts, reviews) emit **no**
  card image → blank previews on iMessage/Slack/X. Resolve
  `seo.image ?? cover ?? portrait ?? appearance.bgImage ?? site.ogImage`; add `site.ogImage`. *(Biggest card gap.)*
- [ ] **JSON-LD: absolute URLs + author + @id** — `image` is a relative path (Google rejects it);
  `author` is missing on `BlogPosting`/`Review` (rich-result requirement); no stable `@id`. Thread
  `site` into `jsonld[type](data, site)`, `abs()` the images, add `author` + `@id` + `mainEntityOfPage`.
- [ ] **favicon + apple-touch-icon + theme-color** — none exist (the icons you flagged earlier).
  Table-stakes branding; `layout.js` + `site.config` + `assets/`.
- [ ] **RSS/Atom feed** — a blog with no feed is a gap (WordPress ships one). `templates/site/feed.js`
  → `feed.xml` + `<link rel="alternate" type="application/rss+xml">`.
- [ ] **404 page** — build `dist/404.html` via `layout()` (Cloudflare Pages auto-serves it).

---

## P1 — strongly want

### Cards / SEO
- [ ] Explicit `twitter:title/description/image` + `twitter:site`/`creator` (handle in `site.config`);
  downgrade `twitter:card` to `summary` when there's no image.
- [ ] `og:image:alt/width/height` (recommend 1200×630); `og:locale`; `article:author`/`article:tag`
  on editorial; `music:musician`/`music:release_date` on releases.
- [ ] BreadcrumbList JSON-LD + a breadcrumb UI; `WebSite` `publisher` (Organization/MusicGroup +
  `sameAs`) + `SearchAction` (when a search page exists).
- [ ] `Review` `itemReviewed` type by `reviewType` (SoftwareApplication vs Product) + brand/url.
- [ ] sitemap `lastmod` on index/home (newest item); `<meta robots content="max-image-preview:large">`.
- [ ] Card image `alt`: `card.js` uses `alt=""` — use the item title. Index `og:title`/`<title>`:
  segments show the raw slug ("releases") — use the nav label.

### AI / LLM
- [ ] `llms.txt` sectioned by type + an `## Endpoints` block; add `llms-full.txt` (full prose for ingestion).
- [ ] Discoverability: `<link rel="alternate" type="application/json" href="/index.json">`; add
  OAI-SearchBot / PerplexityBot / Applebot-Extended to `robots.txt`; reference `llms.txt` there.
- [ ] **Static track list** on releases *before* the facade — bots (and no-JS) can't read the
  click-to-load iframe, so track titles/credits are invisible today.

### Product
- [ ] Validate `site.config.json` in `loadSite()` (the Ajv gate) — clear errors for newcomers.
- [ ] Docs: a 5-minute **Quickstart** (install → init → talk to `/studio` → ship), a content-type/field
  **reference table**, a **skill catalog** in the README.
- [ ] Deploy guide beyond Cloudflare ("any static host; here's the `dist/` contract"); note Netlify/Vercel/Pages.
- [ ] A `/configure-site` skill (or extend `/studio`) to set title/nav/theme/footer conversationally.
- [ ] **Optional AI art generation (xAI/Grok), keychain-gated** — when `GROK_API_KEY` is in the
  Keychain/env, `/studio` offers to generate the *illustrative* art the missing-asset gate surfaces
  (covers, backgrounds, hero/OG images). Opt-in; optional dependency; the key is **presence-probed
  only, never echoed/committed/logged**; generate art (not fake screenshots/photos-as-real). Closes
  the art-backfill loop and is a real AI-native differentiator. (Pairs with the missing-asset gate.)

---

## P2 — polish / trust
- [ ] Perf: bundle/preload the 6 stylesheets; `figure`/`hero` width/height (CLS); `preconnect` for embed
  providers; image `srcset`/`sizes` + an optional optimize pass.
- [ ] `index.json`: add `wordCount`/`excerpt`; a JSON Feed (`/feed.json`) for AI aggregators.
- [ ] oEmbed *provider* endpoint (so Scrybe URLs embed as rich cards in oEmbed-aware tools).
- [ ] missing-asset gate also checks the resolved OG fallback image.
- [ ] CHANGELOG + git tags; CI (test + build on PR); SECURITY note (no runtime/3rd-party JS;
  allowlisted asset fetch); accessibility statement; demo screenshots; CONTRIBUTING.
- [ ] `related` strip by shared tags/genres (topical internal linking); `hreflang`/`site.lang` config.

---

### How to sequence
1. **The two decisions** above (positioning + platform model) — they gate the product P0s.
2. **The web table-stakes P0 batch** (og fallback, JSON-LD fixes, favicon, RSS, 404) — mostly
   `layout.js` + `jsonld` + `build.js`; can ship as one focused pass, no decisions needed.
3. **Product P0s** (scaffold, SCRYBE.md, LICENSE, lockfile) — once positioning is set.
4. P1 SEO/cards/AI enrichment, then P2 polish.

---

## Future support (post-v1 — factor into planning)

### Domain expansion — the general-purpose play
The engine (typed content → blocks → appearance → static HTML + the SEO/AI/cards/feed layer + the
conversational `/studio` flow) is **domain-agnostic**; only the content **types** (schema + renderer +
jsonld + blocks + voice + facts) are music-specific. So "general-purpose" = ship domains as **packs**:
- [ ] Factor the music specifics (release/review schemas, `signalChain`/`abCompare` blocks, producer
  voice, `facts.js` isrc/bpm, music enums) into a **`music` pack**; make the core pack-agnostic.
- [ ] A **type-authoring guide** + ideally a `/new-type` skill (schema + renderer + jsonld + example, conversationally).
- [ ] Example packs that prove the model + bridge from music's "process/craft" voice:
  - **Cooking** → a `recipe` type (ingredients, steps, time, servings, yield) — a big SEO win via
    schema.org **Recipe** rich results; blocks like ingredient-list / step-timer / nutrition.
  - **Gardening** → `plant` / `guide` types (zones, season, care steps) — schema.org **HowTo**.
  The proven ask/answer flow (blog/review/release/profile/layout) is identical; only the type changes.

### WordPress-parity gaps (is this a real WP alternative?)
Beyond the SEO/AI/cards/distribution items above, WP has these we don't:
- [ ] **Taxonomies + archive pages** — tags exist on content, but no `/tag/<x>/` or category archives.
- [ ] **On-site search** — none. A static client-side search over `index.json` fits (and unlocks the JSON-LD SearchAction).
- [ ] **Pagination** — index pages list everything; no paging for large sites.
- [ ] **Generic `page` type** — Terms/Privacy/landing (already noted for Terms/Privacy).
- [ ] **Scheduling** — publish a future-dated item only once its date arrives (drafts exist; future-dating doesn't).
- [ ] **Author pages / multi-author** — `author` field exists; no per-author archive.
- [ ] **Redirects** — generate a Cloudflare `_redirects` from a config map.
- [ ] **Analytics hook** — optional, privacy-respecting `site.analytics` snippet slot (opt-in).
- [ ] **Comments / contact form** — static-friendly only (giscus/utterances; a serverless form) — weigh vs "no 3rd-party funk."
- [ ] **Extensibility model** — Scrybe's plugin analog = blocks + types + themes + skills; document/stabilize the extension surface (the pack model is the core of this).
- [ ] **i18n** — `lang` hardcoded `en`; hreflang + per-site lang (P2) → full multilingual later.

Where Scrybe already beats WP for v1: zero runtime/DB, conversational authoring, AI/LLM discoverability
(llms.txt + structured data), one-config theming/vibe, and the per-type/per-section `appearance` system.