diff --git a/workflows/content-management.md b/workflows/content-management.md new file mode 100644 index 0000000..f838142 --- /dev/null +++ b/workflows/content-management.md @@ -0,0 +1,257 @@ +# Content management guide + +How AiBook.fun content is written, reviewed, shipped, and kept current. + +This is the operating guide for founding writers, Product, and anyone who touches a chapter before Kickstarter. The chapter blank is [`chapter-structure.md`](chapter-structure.md). Product decisions live in [`AiBook_PRD.md`](../AiBook_PRD.md) (§5 content model, §5.4 reading IA). + +--- + +## 1. Source of truth + +**Gitea is the CMS.** Canonical content lives as markdown under `workflows/` on [`WeOwnAI/aibook-fun`](https://git.weown.tools/WeOwnAI/aibook-fun). + +| Role | Path | +|:--|:--| +| Chapter blank (do not fill this in place) | `workflows/chapter-structure.md` | +| One real chapter per vertical | `workflows/[vertical-slug].md` (example: `workflows/real-estate.md`) | +| Sample files shipped with a recipe | `workflows/samples/` or paths named in the recipe kit | + +**Not canonical before Kickstarter** + +- Notion pages +- A separate CMS or “edit on the live site” +- Hand-edited `marketing-site/data/sample-chapter.js` once a real markdown chapter exists (that file is demo residue) + +Authors open a pull request. Reviewers merge to `main`. The reader and PDF read from that tree (directly or through a thin build step). Do not keep a second master copy. + +--- + +## 2. What we are managing + +**A chapter** is a substantial essay for one vertical. Full workflow recipes nest in the argument where they earn their place. Not an appendix. Not a shelf of cards. + +**A workflow recipe** is the unit of practice. The reader reads it, runs the Try-it (~15 min) on sample data, and can share the result. Completing a Try-it is what counts as **activation**. + +**Edition framing.** “2026 edition” / Edition 001 names the catalog year. Billing is `$47/yr`. Recipes are rewritten as tools and models change, often weekly or monthly. Do not describe the book as a once-a-year reprint. + +**Public brand.** Write **AiBook.fun** (capital A, lowercase i). Domain `aibook.fun` stays lowercase. + +--- + +## 3. Roles + +| Role | Owns | +|:--|:--| +| Chapter owner (founding writer) | Draft, kit accuracy, Try-it that actually runs, PR | +| Product | Library sheet (IDs + owners), format gates, claims, merge readiness | +| Second reviewer (another writer or Product) | Structure checklist, safeguards, copy, claims language | +| Runner (author or named tester) | Executes the Try-it on the shipped sample files and records pass/fail | + +One named human owns every Minimum Lovable Library workflow ID. No orphan recipes. + +--- + +## 4. Verticals and IDs + +| Vertical | Slug | ID prefix | +|:--|:--|:--| +| Real Estate | `real-estate` | `RE` | +| Financial Advisors | `financial-advisors` | `FA` | +| Fractional C-Suite | `fractional-c-suite` | `CS` | +| Higher Ed | `higher-ed` | `HE` | +| Communities | `communities` | `CM` | +| Technology | `technology` | `TE` | + +**ID rules** + +- Stable forever once published: `RE-01`, `FA-02`, and so on. +- Founding-library samples start at `01` per vertical unless a real catalog already assigned numbers. +- Do not reuse an ID for a different job. Bump recipe `version` when the steps change. +- URL / anchor form stays lowercase: `re-01` for heading anchors. + +Keep a short **library sheet** (issue or markdown table on `main`) with: ID, short title, chapter file, owner, status (`draft` / `in review` / `shipped`), last Try-it date. + +--- + +## 5. Day-to-day process + +### 5.1 Assign + +1. Product puts the vertical and recipe IDs on the library sheet with a chapter owner. +2. Owner copies `workflows/chapter-structure.md` to `workflows/[vertical-slug].md`. +3. Replace `XX` with the vertical prefix. Delete unused recipe slots. Do not leave hollow blocks. + +### 5.2 Draft + +Write in this order so safeguards are not an afterthought: + +1. Chapter promise and Skip-to-Try-it links +2. What you need (union of kits) +3. Essay sections that earn the first workflow +4. Each nested recipe: **Kit → Problem → Actors → Setup → Safeguards → Method → Evidence → Try-it → Share → Record** +5. Essay continues between recipes where needed +6. Further workflows and Sources + +Rules that do not move (from the blank / PRD §5.4): + +- Skip-to-Try-it at the top +- Safeguards before Method +- Method shows real tool output, not a paraphrase +- Nested recipes stay open (no click-to-reveal Method) +- Every recipe has a kit and a stable ID +- No chatbot on the page +- No crypto, Web3, NFT, or token language +- PDF must match the web stack: essay + in-place recipes + +### 5.3 Kit (required on every recipe) + +Inventory, not instructions. Setup still explains how to use the items. + +- You run +- Tools (named; versions if it matters) +- Files (sample files we ship) +- Model +- Time +- Cost (sample-run amount, or “unknown”) +- You produce (the artifact) + +### 5.4 Run before you ask for review + +The author or a named runner: + +1. Uses only the sample files named in the kit (no live client data) +2. Follows Safeguards, then Method +3. Finishes the Try-it in about the stated time +4. Produces the named artifact +5. Notes model, token/cost if known, and any step that failed + +A recipe that has not been run on its own samples is not ready for merge. + +### 5.5 Pull request + +- Branch from `main` +- One chapter file per PR when possible (samples can land in the same PR) +- PR description lists: recipe IDs touched, who ran the Try-it, date, pass/fail, cost if known +- Link the library sheet row(s) + +### 5.6 Review and merge + +Second reviewer completes the QA checklist below. Product confirms claims language and ID stability. Merge to `main` only when the checklist is green. + +### 5.7 After merge + +- Update the library sheet status and last Try-it date +- Reader / PDF consume `main` (demo JS is not updated by hand as a second source) +- When tools break a step, open a PR that fixes Method and bumps `version`. Do not wait for a yearly reprint. + +### 5.8 Ongoing updates + +As models and products change: + +1. Owner reproduces the break on current tools +2. Patches Method, kit, cost, and sample output +3. Re-runs the Try-it +4. Merges; notes “currency fix” in the PR + +--- + +## 6. Quality assurance + +QA has three layers. All three are required to ship. + +### 6.1 Structure QA (can fail the PR in review) + +- [ ] File is `workflows/[vertical-slug].md`, not an edit of `chapter-structure.md` +- [ ] Front matter: vertical, title, authors, `recipe_ids`, `last_updated` +- [ ] Skip-to-Try-it links resolve to recipe anchors +- [ ] What you need matches the union of recipe kits +- [ ] Each recipe ID matches the library sheet and the vertical prefix +- [ ] Order inside each recipe: Kit, Problem, Actors, Setup, Safeguards, Method, Evidence, Try-it, Share, Record +- [ ] Safeguards appear before Method +- [ ] Method includes real tool output (fenced block or equivalent), not only prose +- [ ] Kit fields are all filled; tools and files are named +- [ ] Try-it names sample data, artifact, and done-when +- [ ] No chatbot; no crypto / Web3 / NFT / token language +- [ ] Brand spelling is AiBook.fun in any product-facing sentence + +### 6.2 Run QA (required evidence in the PR) + +- [ ] Try-it executed on the shipped sample files only +- [ ] Completed in roughly the stated time (±5 min is fine; flag large misses) +- [ ] Artifact produced matches “You produce” +- [ ] Safeguards held (no live client identifiers in prompts) +- [ ] Cost or token note recorded, or explicitly marked unknown +- [ ] Failure modes in Safeguards still match what happened in the run + +### 6.3 Editorial and claims QA + +- [ ] Chapter title and promise are plain facts, not slogan copy (“not X, but Y”) +- [ ] Stakes name a real failure in this vertical +- [ ] Actors separate what the model may do from what a human must do +- [ ] Evidence is an artifact or number, not “the user felt more confident” +- [ ] Share line shares the outcome, not the recipe text +- [ ] Any figure that could appear on Kickstarter or the marketing site is on the claims register or removed +- [ ] Pricing language matches signed decisions: `$47/yr`, no lifetime SKU as an equal v1 product +- [ ] Contribution / “stake” language matches D-2 / D-6 (authored v1; paid contribution is Layer 2; no token ownership claims) + +### 6.4 Reader QA (before a chapter is linked from `/read` or the campaign) + +- [ ] Chapter opens from the Library with correct breadcrumb +- [ ] Skip-to-Try-it and in-chapter outline jump to the right anchors +- [ ] Kit shows on the chapter and on each nested recipe +- [ ] Mark-complete / activation demo still works if that surface is live +- [ ] Print / focus view matches the nested recipe content + +--- + +## 7. Definition of done + +A workflow is **shipped** when: + +1. It has a stable ID and named owner on the library sheet +2. It lives in a merged chapter file on `main` +3. Structure QA, Run QA, and Editorial QA all passed +4. A second person signed the review (PR approval is enough) + +A chapter is **preview-ready** (backer sample) when at least two nested workflows are shipped inside it and Reader QA passed. + +The **Minimum Lovable Library** floor is 15–20 shipped workflows across at least three verticals, each with a named author (Gate 0 / Implementation Plan). + +--- + +## 8. Claims and public surfaces + +Anything that can appear on Kickstarter, the marketing site, email, or social: + +- Must match merged content or the signed product decisions +- Must not invent activation rates, contributor counts, or ownership language +- Goes through the claims register when Product opens it + +Marketing site copy points at the Library. It does not become a second place to maintain recipes. + +--- + +## 9. Quick start (one chapter) + +```text +1. Copy workflows/chapter-structure.md → workflows/real-estate.md +2. Fill RE-01 and RE-02 (kit first, then safeguards, then method with real output) +3. Add sample files named in the kits +4. Run both Try-its; note results in the PR +5. Open PR → second reviewer runs §6 checklists → merge +6. Update library sheet; link chapter from the reader when the build path is ready +``` + +--- + +## 10. Related files + +| File | Why | +|:--|:--| +| [`workflows/chapter-structure.md`](chapter-structure.md) | Blank chapter + recipe shape | +| [`AiBook_PRD.md`](../AiBook_PRD.md) | Content model, reading IA, activation | +| [`AiBook_Spec.md`](../AiBook_Spec.md) | Spec detail | +| [`AiBook_Implementation_Plan.md`](../AiBook_Implementation_Plan.md) | MLL floor, Gate 0, content critical path | +| `marketing-site/pages/read/` | Reading demo only until markdown feed exists | + +**Last updated:** 10 Sep 2026