258 lines
10 KiB
Markdown
258 lines
10 KiB
Markdown
# 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
|