docs: add card content workflow to AGENTS.md, create QUICKSTART.md

AGENTS.md: document SVG → PDF → ITEMS.md flow. SVGs are master source;
ITEMS.md is derived. Never edit ITEMS.md directly or run
generate-source-of-truth.py in a worktree (drops consensus blocks).

QUICKSTART.md: captures repo structure, source-of-truth chain, lore
pipeline, worktree gotchas, and voice guide for agent onboarding.

Made-with: Cursor
This commit is contained in:
2026-04-16 19:11:27 +02:00
parent b6832468c5
commit 8f6dbf3aac
2 changed files with 139 additions and 0 deletions
+22
View File
@@ -53,6 +53,28 @@ When archiving a change (`openspec-archive`), always perform the complete close-
"Done" means done — no orphan worktrees, no unmerged branches, no unpushed commits.
## Card Content Workflow: SVG → PDF → ITEMS.md
**SVGs are the master source for card content.** ITEMS.md is a derived document generated from SVGs by `scripts/generate-source-of-truth.py`. Never edit ITEMS.md directly — it will be overwritten on the next regeneration.
PDFs (`**/*.pdf`), images (`**/*.png`), and raw materials (`raw-materials*/`) are gitignored. They only exist in the main checkout's local filesystem, not in worktrees.
**Workflow for card content changes (lore, mechanics, etc.):**
1. **Edit SVGs in the worktree** — use `scripts/rewrite-lore.py` for lore-only changes, or `scripts/generate-card.py` for full card generation.
2. **Commit SVG changes and merge to integration branch** from the main checkout.
3. **From the main checkout** (which has raw materials and PDF directories), regenerate derived artifacts:
```bash
# Export player PDFs for changed cards
python3 scripts/export-player-pdf.py "path/to/card.svg" \
-o "path/to/PDFs Players/Singles/Card Name (price).pdf"
# Regenerate ITEMS.md (use --tier to target a single tier)
python3 scripts/generate-source-of-truth.py --tier "0c Specialist"
```
**Key constraint:** `generate-source-of-truth.py` requires raw materials for consensus negotiation blocks and image references. Running it in a worktree will silently drop that data. Always run it from the main checkout after merge.
## Lock File Contract
Each active worktree contains `.agent-lock` with owner/task/timestamp. If lock ownership is unclear, stop and ask before making edits.
+117
View File
@@ -0,0 +1,117 @@
# Agent Quickstart
Things the last agent had to figure out by exploration. Read this before you start.
## What This Repo Is
D&D item cards for a homebrew "Northlands Guild" setting. Each item is a credit-card-sized SVG with a front (mechanics) and back (lore). SVGs are the working files; PDFs are generated for printing.
## Key Files to Read First
| File | What it tells you |
|------|------------------|
| `.cursor/skills/guild-pack-cards/SKILL.md` | Full pipeline docs, style guide, lore voice, pitfalls 1-18 |
| `AGENTS.md` | Worktree isolation rules, PDF workflow, source-of-truth contract |
| `HANDOFF.md` | Current work queue (if one exists) |
| `scripts/README.md` | Detailed script reference |
## Repo Structure
```
0a Novice/ — Tier 0a, handmade mini-items
0b Intermediate/ — Tier 0b, handmade full items
0c Specialist/ — Tier 0c (Tier-1), 7 flavor subdirs
Defense/
Magic/
Offense/
Recovery/
Stealth/
Strike/
Utility/
1 Capable/ — Tier-2, same flavor structure
2 Expert/ — Tier-3
3 Master/ — Tier-4
4 Grandmaster/ — Tier-5
5 Exit/ — Tier-6
scripts/ — Python pipeline
raw-materials*/ — Historical text/images (gitignored)
```
Each tier folder contains:
- `*.svg` — Card source files (DM version with both front + back) — **master source**
- `ITEMS.md` — Derived document, generated from SVGs by `generate-source-of-truth.py`
- `PACKS.md` — Pack composition
- `BALANCE.md` — Price/rarity summary
- `PDFs Players/Singles/` — Player-facing PDFs (gitignored)
## The Source of Truth Chain
**SVGs are the master source.** ITEMS.md is derived from SVGs — never edit ITEMS.md directly.
The flow is always: **SVG → PDF → ITEMS.md**
1. Edit lore/mechanics in the SVG (via `rewrite-lore.py` or `generate-card.py`)
2. Commit SVGs, merge to integration branch
3. From the main checkout: export PDFs, then regenerate ITEMS.md
`generate-source-of-truth.py --tier "0c Specialist"` regenerates ITEMS.md for one tier (use `--tier` to avoid processing all 8 tiers). It must run from the main checkout where raw materials live.
## How Lore Gets Into SVGs
SVG lore lives in `<text>` elements with `shape-inside` style and a matrix transform with x_offset > 50. The text is stored as `<tspan>` elements with explicit x/y coordinates.
### To rewrite lore on an existing card:
```bash
python3 scripts/rewrite-lore.py "path/to/Card.svg" "New lore text here..."
```
This uses the same `format_lore_text()` + `set_text_content()` pipeline as `generate-card.py`. It handles paragraph splitting, quote detection, and tspan layout automatically.
**NEVER** extract lore from SVG tspans, edit it, and reinsert. Tspan line-wrap boundaries eat spaces when concatenated (e.g., "percentof", "aresolved"). Always write complete clean text.
### To generate a card from scratch:
```bash
python3 scripts/generate-card.py \
--template "path/to/template.svg" \
--item-text "raw-materials/.../Item [Rarity] [Price].txt" \
--image "raw-materials/.../Item_1.png" \
--lore-choice main \
--output "path/to/output.svg" \
--flavor Recovery --tier 0c
```
### To export player PDFs:
```bash
python3 scripts/export-player-pdf.py "path/to/card.svg" \
-o "path/to/PDFs Players/Singles/Card Name (price).pdf"
```
Requires Inkscape (`inkscape` on PATH). Only works in the main checkout where PDFs live.
## Worktree Gotchas
1. **Raw materials are gitignored.** `raw-materials*/` won't exist in worktrees. Scripts that need them (`generate-source-of-truth.py`, `batch-generate.py`) must run from the main checkout.
2. **Never run `generate-source-of-truth.py` in a worktree.** Without raw materials, it silently drops consensus negotiation blocks and image references from ITEMS.md. Always run it from the main checkout after merging SVG changes.
3. **Never edit ITEMS.md directly.** It's a derived document. Edit the SVG, merge, then regenerate ITEMS.md from the main checkout.
4. **PDFs are gitignored.** Generate them from the main checkout after merging.
5. **Only commit SVGs from worktrees.** The post-merge workflow (PDFs + ITEMS.md regeneration) happens in the main checkout.
## Lore Voice (TL;DR)
Tired, competent quartermaster filing field reports who happens to be funnier than they intend. Terry Pratchett footnotes meet British civil servant describing a dragon attack with understatement.
- **Opening**: Origin story or physical description with unexpected angle. Never "this item does X."
- **Middle**: In-character experience of using the item. Class/profession reactions for contrast.
- **Closing**: Earned punchline, practical warning, or dry observation.
- **No puns.** Humor is structural and observational.
- **No boilerplate.** See SKILL.md pitfall #10 and #14 for known boilerplate signals.
- **100-120 words**, 3-4 paragraphs.
Read the exemplar lore in SKILL.md and study the Master tier (Tier-4) entries in `3 Master/ITEMS.md` for tone calibration.