@ericrisco/rsc 0.1.34 → 0.1.36

package/skills/level-design/references/pacing-and-encounters.md

@@ -0,0 +1,142 @@
+# Pacing & encounters — rhythm, arenas, and teaching through space
+
+A level is a piece of music, not a list of rooms. This reference covers the
+intensity graph, the breather, the difficulty curve, the encounter template, the
+introduce→develop→twist→combine teaching pattern, and arena-shape design.
+
+## The intensity graph
+
+Plot intended intensity (danger + cognitive load + stimulus) against time for
+the whole level. The target shape is a **sawtooth trending upward**: a peak
+(combat, chase, platforming gauntlet, tense stealth), a sharp drop to a valley
+(a breather), then a higher peak. Overall the line climbs, ending on the level's
+hardest, most spectacular moment.
+
+```text
+intensity
+  ^                                        ___/\   <- climax (hardest, last)
+  |            ___/\           ___/\      /
+  |     __/\  /     \    __/\  /     \___/
+  |  __/    \/       \__/    \/            <- breathers (valleys)
+  +---------------------------------------------> time
+     intro  peak  rest  peak  rest  build  climax
+```
+
+Two failure shapes to avoid:
+
+- **Flat-high** — sustained maximum intensity. The player fatigues and the peaks
+  stop reading as peaks; it flattens into undifferentiated noise. This is the
+  most common "my level is exhausting / boring despite lots of action" cause.
+- **Flat-low** — long stretches with no tension or stimulus. Reads as padding
+  and boredom even if each individual moment is competent.
+
+Draw this graph *before* building encounters; it tells you where fights go and
+how long the gaps between them should be.
+
+## The breather (safe room)
+
+After each peak, a valley: a **safe room** with no threat, low stimulus, and
+usually a save point and/or restock. The breather does three jobs:
+
+1. **Lets adrenaline drop** so the next peak spikes instead of blending in.
+   (Halo's cadence is often described as "thirty seconds of fun" on repeat — the
+   calm between is what makes the fun read.)
+2. **Rewards observation** — a quiet room is where lore, a secret, or a vista
+   lands, because the player has attention to spare.
+3. **Sets up the next escalation** — telegraph what's coming (a locked blast
+   door, distant sound, a corpse) so the next peak feels earned, not random.
+
+Vary breather length with the peak that preceded it: a brutal fight earns a
+longer rest; a light skirmish gets a short beat.
+
+## Difficulty curve within a level
+
+The macro trend is up, but it **resets at checkpoints** — the sawtooth again.
+Let the player re-enter a checkpoint competent and confident, then ramp. A curve
+that only climbs with no resets feels punishing; one that never climbs feels
+trivial. Signposting difficulty (a visibly tougher enemy, a bigger arena) lets
+the player brace, which is fairer than a surprise spike.
+
+## Encounter design
+
+An **encounter = enemy composition × space × objective × available resources.**
+Change any single factor to create a fresh encounter without new assets:
+
+- **Composition** — which enemy types, how many, in what waves.
+- **Space** — the arena shape (below); the same enemies feel new in a new arena.
+- **Objective** — kill all / survive N seconds / reach the exit / protect / hold
+  ground / retreat. The objective reshapes how the space is used.
+- **Resources** — ammo, health, cover, high ground the player can seize.
+
+### The encounter template
+
+```text
+ENCOUNTER — <name>
+  Teaches / tests ..... which mechanic or threat (and which of I/D/T/C beat)
+  Space ............... arena shape, sightline length, cover, flanks, verticality
+  Composition ......... enemy types + counts + wave timing
+  Objective ........... win condition (kill / survive / reach / hold / escort)
+  Resources ........... ammo/health/cover/high-ground and where they sit
+  Entry / exit ........ how the player arrives (telegraph) and leaves (release valve)
+  Intensity ........... where this sits on the level's graph (peak height)
+```
+
+## Introduce -> develop -> twist -> combine
+
+The four-beat progression that teaches a new element through space, without
+text. (The pattern behind Portal's test chambers, Half-Life 2's set-pieces, and
+much Nintendo level craft.)
+
+1. **Introduce** — meet it where it cannot hurt you. A turret across a safe gap;
+   one tile of the new hazard with a wall to watch from. Zero-risk learning.
+2. **Develop** — use it for real, low stakes. The turret now guards a corridor
+   you must cross; the hazard is a gap you must jump.
+3. **Twist** — recontextualize it. Two turrets flanking; the turret behind glass
+   you must lure enemies past; the hazard now moves. The rule you learned bends.
+4. **Combine** — the mastery test: the new element + everything learned earlier,
+   at full intensity, as the section's climax.
+
+### Worked example — a "gravity plate" that flings the player upward
+
+- **Introduce**: one plate in a safe room; step on it, get flung to a ledge with
+  a reward. No threat. Player learns "plate = launch."
+- **Develop**: cross a pit by chaining two plates — miss and you just fall back,
+  retry. Low stakes, real use.
+- **Twist**: a plate launches you *into* a turret's line of fire — now you must
+  time the launch, or use the plate to reach the turret's flank.
+- **Combine**: an arena where plates are the only way to reach high cover, under
+  fire, while enemies also use them. Everything at once.
+
+## Arena shape — the geometry is the difficulty knob
+
+The shape a fight happens in matters as much as the enemies:
+
+- **Sightline length ↔ threat range.** Long lanes favor ranged play and
+  sniping; tight rooms favor shotguns/melee and force close engagements. Set the
+  lane length to the range you want to be dominant.
+- **Cover rhythm.** Space cover so the player *advances in beats* — peek, move,
+  peek — rather than turtling in one spot. Low cover (peek over) vs full cover
+  (peek around) change the fight's tempo.
+- **Flanks.** Give at least one flank route so a fight isn't a static peek-war;
+  a flank forces the player to move and makes the space three-dimensional in
+  play, not just in geometry.
+- **Verticality.** High ground is pressure and reward. The Doom (2016) arena
+  is the reference: multi-tier, with resources and enemies placed to pull the
+  player *through* and *up* the space rather than hunker in a corner.
+- **Chokepoints + release valves.** A choke concentrates danger (good for a
+  last stand); always pair it with an exit or a way to break the standoff, or
+  the fight stalls into a stalemate.
+- **Entry and exit.** Telegraph the fight before the player commits (see the
+  arena from a safe threshold), and give a clear release when it's won.
+
+### Arena patterns
+
+| Pattern | Shape | Good for |
+|---|---|---|
+| **Corridor / lane** | Long, narrow, few flanks | Tension, forced pace, ranged duels |
+| **Open arena** | Wide, multi-cover, multi-flank | Skill expression, mobile fights |
+| **Vertical arena** | Stacked tiers, ramps/lifts | High-ground contests, push-forward combat |
+| **Hub** | Central space, spokes off it | Wave defense, "hold ground" objectives |
+| **Pinch** | Wide → choke → wide | Escalation, last-stand beats |
+
+Match the pattern to the encounter's job on the intensity graph, not to habit.

package/skills/linkedin-api/SKILL.md

@@ -169,6 +169,13 @@ Filename: the post id slug, e.g. `02-DOCS/wiki/linkedin/share-701234567890123456
 
 ```markdown
 ---
+type: linkedin-record
+title: "Share 7012345678901234567 — OAuth pitfalls carousel"
+description: Performance snapshot for one LinkedIn post, pulled from organizationalEntityShareStatistics.
+tags: [linkedin, analytics, post-performance]
+timestamp: "2026-06-02T10:00:00Z"
+topic: linkedin
+status: stable
 post_urn: "urn:li:share:7012345678901234567"
 author: "urn:li:organization:12345"
 captured_at: "2026-06-02T10:00:00Z"
@@ -181,11 +188,13 @@ shares: 8
 engagement: 0.0683
 ---
 
+# Share 7012345678901234567 — OAuth pitfalls carousel
+
 Carousel on OAuth pitfalls. Highest unique-impression post this month;
 CTR ~4.4%. The "common 403 causes" hook outperformed the plain howto.
 ```
 
-Keep the front-matter keys exactly as above — `verify.sh` checks that `post_urn`, `captured_at`, `impressions`, and `engagement` are present in every file under that directory.
+`type` is the only required OKF v0.1 field; `title`/`description`/`tags`/`timestamp` are the recommended OKF surface. The DOMAIN keys below them are mandatory and must stay byte-for-byte — `verify.sh` checks that `post_urn`, `captured_at`, `impressions`, and `engagement` are present in every file under that directory. `captured_at` is the API-capture instant (a domain value verify.sh parses); `timestamp` is the OKF last-edit field — keep both. Note these files share `02-DOCS/wiki/linkedin/` with `linkedin-strategy`; using `type: linkedin-record` keeps the two skills' wiki content consistent.
 
 ## Anti-patterns
 

package/skills/linkedin-strategy/SKILL.md

@@ -131,6 +131,16 @@ Engagement rising while cadence held?
 Append a dated decision record under `02-DOCS/wiki/linkedin/decisions/`. Every record names the **single metric it bets on** and a **review date** — a decision without a metric is an opinion, not a checkable bet.
 
 ```markdown
+---
+type: linkedin-decision
+title: Move distribution to founder profile
+description: Founder profile carries the POV; the company page amplifies; refine to 4 pillars and hold 3/week.
+tags: [linkedin, distribution, positioning, cadence]
+timestamp: 2026-06-02T00:00:00Z
+topic: linkedin
+status: stable
+---
+
 # 2026-06-02 — Move distribution to founder profile
 
 Context read: SSI 48 (flat 90d); top-2 dwell-time posts both carousels on
@@ -144,6 +154,8 @@ Bets on metric: SSI 48 -> 65 within 90 days (proxy for inbound).
 Review date: 2026-09-02.
 ```
 
+The `type:` field is required (OKF v0.1); `timestamp` is ISO 8601. The dated heading and the `Decision:` / `Bets on metric:` / `Review date:` lines are domain signals `verify.sh` greps for — keep them.
+
 After writing, run `scripts/verify.sh 02-DOCS/wiki/linkedin/` to confirm the record is structurally complete. Full templates and the what-worked format: `references/wiki-records.md`.
 
 ## Anti-patterns

package/skills/linkedin-strategy/references/wiki-records.md

@@ -2,6 +2,8 @@
 
 The read/write loop's storage. Everything is append-only markdown so future strategy sessions compound instead of restarting from generic advice.
 
+Every `.md` file written here is part of the `02-DOCS/wiki/` OKF v0.1 bundle, so each carries YAML frontmatter with a non-empty `type:` (the only required OKF field). Cross-references between files use **standard markdown links** (`[Text](./pillars.md)`) — never wikilinks (`[[...]]`). The domain lines `verify.sh` greps for (the dated heading, `Decision:`, the metric/bet field) stay exactly as below.
+
 ## File layout
 
 ```text
@@ -18,13 +20,23 @@ A running `decisions.md` log at the root is also accepted instead of `decisions/
 
 ## Bootstrap (empty/absent dir)
 
-When `02-DOCS/wiki/linkedin/` does not exist, create it with `positioning.md`, `pillars.md`, `decisions/`, and `what-worked.md` before you decide. Seed `positioning.md` with whatever the account already implies (title, current posts) so the first decision has a baseline to react to.
+When `02-DOCS/wiki/linkedin/` does not exist, create it with `positioning.md`, `pillars.md`, `decisions/`, and `what-worked.md` before you decide. Seed `positioning.md` with whatever the account already implies (title, current posts) so the first decision has a baseline to react to. Each of `positioning.md`, `pillars.md`, and `what-worked.md` gets OKF frontmatter — use `type: linkedin-positioning`, `type: linkedin-pillars`, and `type: linkedin-record` respectively (templates below).
 
 ## Decision-record template
 
 Every record carries: a dated heading, a context-read line (what you grounded in), a decision line, the single metric it bets on, and a review date. Missing the metric or the review date means it is not a checkable bet.
 
 ```markdown
+---
+type: linkedin-decision
+title: <short decision title>
+description: <one-sentence summary of the choice>
+tags: [linkedin, <pillars|cadence|distribution|ssi>]
+timestamp: <YYYY-MM-DDTHH:MM:SSZ>
+topic: linkedin
+status: stable
+---
+
 # 2026-06-02 — <short decision title>
 
 Context read: <what you pulled from the wiki — prior positioning, current pillars,
@@ -39,9 +51,23 @@ SSI 48 -> 65 within 90 days, or median dwell time +X%, or inbound DMs/week>.
 Review date: <YYYY-MM-DD — when the next session checks whether the bet paid>.
 ```
 
+`type` (required) + `timestamp` (ISO 8601, last meaningful edit) are the OKF surface; everything below the frontmatter is the domain content `verify.sh` checks. A running `decisions.md` log at the root carries one frontmatter block at the top (`type: linkedin-decision`); its dated `## ` entries are prepended newest-first and never edited.
+
 ## what-worked template
 
+`what-worked.md` is a single running file; new review blocks are prepended newest-first under one frontmatter block at the top.
+
 ```markdown
+---
+type: linkedin-record
+title: What worked — LinkedIn
+description: Running log of which pillars, formats, and posts earned dwell time and SSI movement.
+tags: [linkedin, what-worked, dwell-time, ssi]
+timestamp: 2026-09-02T00:00:00Z
+topic: linkedin
+status: stable
+---
+
 ## 2026-09-02 review
 
 - Pillar "pipeline reliability" — RISING. 2 carousels in top-3 dwell time. Double down.

package/skills/marketing/references/brand-grounding.md

@@ -91,9 +91,19 @@ If the user can't answer a question, that dimension stays incomplete — note th
 
 ### Brand wiki article template
 
-Each `02-DOCS/wiki/brand/*.md` article follows the harness wiki format:
+Each `02-DOCS/wiki/brand/*.md` article follows the harness wiki format. It is an OKF v0.1 article: open it with YAML frontmatter carrying a non-empty `type:` (`brand-study`), then the H1 and body:
 
 ```markdown
+---
+type: brand-study
+title: Brand — Value Proposition
+description: The core benefit and what makes this brand different from the named alternatives.
+tags: [brand, value-proposition]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: brand
+status: stable
+---
+
 # Brand — Value Proposition
 
 > Sources: {user interview, YYYY-MM-DD}
@@ -124,9 +134,19 @@ One paragraph: the core benefit and what makes it different.
 
 ### Voice article specifics
 
-`voice.md` must contain the do/don't word lists and link to every raw sample:
+`voice.md` must contain the do/don't word lists and link to every raw sample (same OKF frontmatter; `type: brand-study`):
 
 ```markdown
+---
+type: brand-study
+title: Brand — Tone & Voice
+description: Tone descriptors, do/don't word lists, and the voice fingerprint extracted from real samples.
+tags: [brand, voice, tone]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: brand
+status: stable
+---
+
 # Brand — Tone & Voice
 
 > Sources: {user interview, YYYY-MM-DD}

package/skills/medium-strategy/SKILL.md

@@ -133,6 +133,16 @@ On a monthly/quarterly review:
 Every session ends with a dated record under `02-DOCS/wiki/medium/decisions/`. Minimum fields — the bet-on metric is mandatory, because a decision with no metric is an opinion, not a checkable bet:
 
 ```markdown
+---
+type: medium-decision
+title: Solo vs publication for AI-tools series
+description: Stay solo + canonical-import the blog series; pitch one Boost-eligible AI pub with a native original.
+tags: [medium, publications, monetization, distribution]
+timestamp: 2026-06-02T00:00:00Z
+topic: medium
+status: stable
+---
+
 # 2026-06-02 — Solo vs publication for AI-tools series
 
 Decision: Stay solo profile + canonical-import the blog series; pitch one Boost-eligible AI pub with a native original.
@@ -140,6 +150,8 @@ Rationale: 400 followers, no editor nomination path; the blog has evergreen sear
 Bets on metric: member reading time from external/search referral; 1 Boost nomination this quarter.
 ```
 
+`type:` is the required OKF v0.1 field; `timestamp` is ISO 8601. The `Decision:` / `Bets on metric:` lines are domain signals `verify.sh` greps for — keep them.
+
 After a review, append a `what-worked.md` entry tied to specific stories/pubs/tags (e.g. "`AI Coding Tools` long-tail + Boost → 3.2h member reading time"). Full templates, layout, and the verify.sh contract: [`references/wiki-records.md`](references/wiki-records.md). Sanity-check the wiki with `scripts/verify.sh 02-DOCS/wiki/medium/`.
 
 ## Anti-patterns

package/skills/medium-strategy/references/wiki-records.md

@@ -2,6 +2,8 @@
 
 This is the persistence layer that makes medium-strategy compound. Read SKILL.md §1 and §9 first; this file is the exact format.
 
+Every `.md` file written under `02-DOCS/wiki/medium/` is part of the OKF v0.1 bundle: it carries YAML frontmatter with a non-empty `type:` (the only required OKF field), and any cross-references use **standard markdown links** (`[Text](./pubs.md)`), never wikilinks (`[[...]]`). The domain lines `verify.sh` greps for (the dated heading, `Decision:`, the metric/bet field) stay exactly as shown below.
+
 ## Layout under `02-DOCS/wiki/medium/`
 
 ```text
@@ -21,6 +23,16 @@ This is the persistence layer that makes medium-strategy compound. Read SKILL.md
 Every decision file MUST carry three signals: a **date**, a **Decision:** line, and a **named metric/bet**. The metric is mandatory — a decision with no metric is an opinion, not something you can check next quarter.
 
 ```markdown
+---
+type: medium-decision
+title: Solo vs publication for the AI-tools series
+description: Stay solo; canonical-import the evergreen blog posts; pitch one Boost-eligible AI pub.
+tags: [medium, publications, monetization, distribution]
+timestamp: 2026-06-02T00:00:00Z
+topic: medium
+status: stable
+---
+
 # 2026-06-02 — Solo vs publication for the AI-tools series
 
 Decision: Stay solo profile; canonical-import the 6 evergreen blog posts; pitch one Boost-eligible AI publication with a new native original.
@@ -29,11 +41,23 @@ Bets on metric: member reading time from external + search referral over 90 days
 Status: open
 ```
 
-When the bet resolves, append a short outcome to the same file (`Status: won — Boost nomination 2026-07; +2.1h member reading time`) rather than editing the original — append-only history.
+`type:` (required) + `timestamp:` (ISO 8601, last meaningful edit) are the OKF surface; the `Status:` line in the body is the domain bet-lifecycle marker — distinct from the frontmatter `status:` (the OKF article lifecycle: draft | stable | stale). When the bet resolves, append a short outcome to the body (`Status: won — Boost nomination 2026-07; +2.1h member reading time`) rather than editing the original — append-only history. A running `decisions.md` log at the root carries one frontmatter block at the top (`type: medium-decision`).
 
 ## what-worked.md entry template
 
+`what-worked.md` is one running file; new review blocks are prepended newest-first under a single frontmatter block at the top.
+
 ```markdown
+---
+type: medium-record
+title: What worked — Medium
+description: Running log of outcomes tied to specific Medium stories, publications, and tags.
+tags: [medium, what-worked, member-reading-time, boost]
+timestamp: 2026-09-01T00:00:00Z
+topic: medium
+status: stable
+---
+
 ## 2026-09-01 — Q3 review
 - `AI Coding Tools` (long-tail) + Boost → 3.2h member reading time on one story. Double down: keep the long-tail tag, pitch the same pub again.
 - Imported blog post w/ canonical + newsletter push → +5% external bonus visible, but low member conversion. Keep importing; stop expecting member reads from cold list.
@@ -44,6 +68,20 @@ When the bet resolves, append a short outcome to the same file (`Status: won —
 
 Keep these lightweight. `pubs.md`: pub name | status (accepted/pitched/dropped) | niche fit | a one-line guideline note. `tags.md`: tag | popular-or-long-tail | did it pull member reading time?
 
+Both still carry OKF frontmatter (one block at the top of each file):
+
+```markdown
+---
+type: medium-record
+title: Publications tracker   # or: Tag sets tried
+description: Accepted / pitched / dropped Medium publications and their guideline notes.
+tags: [medium, publications]   # or [medium, tags, distribution] for tags.md
+timestamp: 2026-09-01T00:00:00Z
+topic: medium
+status: stable
+---
+```
+
 ## The verify.sh contract
 
 `scripts/verify.sh` is a **structural lint, not a craft judge.** Run it after a session:

package/skills/medium-writing/SKILL.md

@@ -117,6 +117,25 @@ If `02-DOCS/` exists, learn before you write:
 - Bias toward the title/subtitle patterns and topics that historically beat a 50% read ratio for *this* author; avoid angles that drew clicks but bounced.
 - After a notable result, append the learned pattern to `02-DOCS/wiki/medium/read-ratio-patterns.md` so the next draft inherits it.
 
+`read-ratio-patterns.md` lives in the `02-DOCS/wiki/` OKF v0.1 bundle, so it carries YAML frontmatter with a non-empty `type:` — one block at the top, with new pattern blocks prepended newest-first below it. Use `type: medium-record` (the same type the `medium-strategy` skill writes under `02-DOCS/wiki/medium/`, keeping the two skills' wiki content consistent). Create it with this header if it does not yet exist:
+
+```markdown
+---
+type: medium-record
+title: Read-ratio patterns — Medium
+description: Title/subtitle/topic patterns that historically beat a 50% read ratio for this author.
+tags: [medium, read-ratio, titles, hooks]
+timestamp: 2026-06-02T00:00:00Z
+topic: medium
+status: stable
+---
+
+## 2026-06-02 — <pattern learned>
+- <title/subtitle archetype + topic that beat the 50% read ratio, with the number observed>
+```
+
+Cross-references use standard markdown links (`[Text](./what-worked.md)`), never wikilinks (`[[...]]`).
+
 If `02-DOCS/` is absent, proceed from the craft defaults above and say so in one line, rather than inventing stats.
 
 ## Anti-patterns

package/skills/plan/references/plan-template.md

@@ -9,9 +9,20 @@ flows, levels — not framework syntax.
 ---
 
 ```markdown
+---
+type: plan
+title: Plan — <feature name>
+description: The structure-level implementation plan for <feature> — contracts, shapes, flows.
+tags: [sdd, plan]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: sdd
+slug: <slug>
+status: draft
+---
+
 # Plan — <feature name>
 
-> Spec: ../specs/<slug>.md · Constitution: ../constitution.md · Status: draft | approved
+> Spec: [../specs/<slug>.md](../specs/<slug>.md) · Constitution: [../constitution.md](../constitution.md) · Status: draft | approved
 > Last updated: YYYY-MM-DD
 
 ## 0. Global Constraints

package/skills/shortform-packaging/SKILL.md

@@ -63,8 +63,13 @@ stranger's voice that contradicts what already won.
 4. **No script or no settled angle? Route OUT** (see Handoffs). Never invent here.
 
 Persist the package under `02-DOCS/wiki/shortform/` and raw test results under
-`02-DOCS/raw/shortform/`. Pattern depth lives in
-[references/package-templates.md](references/package-templates.md).
+`02-DOCS/raw/shortform/`. The `shortform/` wiki tree is an **OKF v0.1 bundle** shared
+with the `tiktok-api` and `shortform-strategy` siblings: each persisted package `.md`
+leads with YAML frontmatter carrying a non-empty `type: shortform-package` (plus the
+recommended `title`/`tags`/`timestamp`), and any cross-references use standard markdown
+links, never `[[wikilinks]]`. The raw feedback log under `02-DOCS/raw/shortform/` is
+`raw/`, not `wiki/` — no frontmatter required. The full frontmatter + pattern depth
+lives in [references/package-templates.md](references/package-templates.md).
 
 ## The two-second decision
 

package/skills/shortform-packaging/references/package-templates.md

@@ -6,10 +6,21 @@ filled `02-DOCS` feedback-log schema.
 
 ## The package file format
 
-Emit one plain-text/markdown block per short. `scripts/verify.sh` lints exactly these
-labels (English or ES/CA, one per line, content following):
+Emit one markdown file per short under `02-DOCS/wiki/shortform/`. The `shortform/`
+wiki tree is an **OKF v0.1 bundle** shared with the `tiktok-api` and
+`shortform-strategy` siblings, so the file leads with YAML frontmatter (a non-empty
+`type` is the only OKF hard requirement; `title`/`tags`/`timestamp` are the recommended
+surface). The labeled body below is unchanged — `scripts/verify.sh` lints exactly these
+labels (English or ES/CA, one per line, content following) and ignores the frontmatter:
 
 ```text
+---
+type: shortform-package
+title: faceless productivity TikTok — package
+tags: [shortform, packaging, tiktok]
+timestamp: 2026-06-02T12:00:00Z
+platform: tiktok
+---
 Hook:
   - I deleted my to-do app. Here's why.
   - The app that runs my whole week (it's free)

package/skills/shortform-strategy/SKILL.md

@@ -113,9 +113,21 @@ Every decision must end up in the ledger so next month's call is grounded.
 
 ### Decision record format
 
-Append every call to `02-DOCS/wiki/shortform/decisions.md` as a dated block:
+`02-DOCS/wiki/shortform/decisions.md` is an OKF append-log: write the frontmatter
+header once (a non-empty `type` is the only OKF hard requirement; `title`/`tags`/`timestamp`
+are the recommended surface), then **prepend each new dated block newest-first** so the
+latest call is on top. Use ISO 8601 dates; never edit a past block. Bump the header
+`timestamp` on each append. Header + one block:
 
 ```markdown
+---
+type: shortform-decision-log
+title: Shortform strategy decisions
+tags: [shortform, strategy, decisions]
+timestamp: 2026-06-02T10:00:00Z
+---
+# Shortform strategy decisions
+
 ## 2026-06-02 — Drop daily posting to 4 Reels/week
 **Decision:** Cut from ~7 thin posts/week to 4 strong Reels/week, fixed Tue/Fri.
 **Rationale:** Reach fell as volume rose; consistency > velocity past the ceiling.
@@ -140,10 +152,22 @@ Append every call to `02-DOCS/wiki/shortform/decisions.md` as a dated block:
 
 ## Persist it
 
-Write the account's brain back so it compounds (mirrors the harness Karpathy-wiki convention):
+Write the account's brain back so it compounds (mirrors the harness Karpathy-wiki convention). The `shortform/` wiki tree is an **OKF v0.1 bundle** shared with the `tiktok-api` and `shortform-packaging` siblings: every `.md` written here carries YAML frontmatter with a non-empty `type`, cross-references are standard markdown links (never `[[wikilinks]]`), and `decisions.md` follows the OKF newest-first append-log rule.
+
+- `02-DOCS/wiki/shortform/strategy.md` — positioning, cadence/mix, KPI, length bands, current series. Lead with frontmatter; the body keeps the H1 + sections the linter checks:
+
+  ```markdown
+  ---
+  type: shortform-strategy
+  title: Shortform account strategy
+  tags: [shortform, strategy, positioning, cadence]
+  timestamp: 2026-06-02T10:00:00Z
+  ---
+  # Shortform account strategy
+  ...
+  ```
 
-- `02-DOCS/wiki/shortform/strategy.md` — positioning, cadence/mix, KPI, length bands, current series.
-- `02-DOCS/wiki/shortform/decisions.md` — the dated decision log (format above).
-- `02-DOCS/raw/shortform/metrics.csv` — the per-post ledger (schema in `references/learning-loop-template.md`).
+- `02-DOCS/wiki/shortform/decisions.md` — the dated decision log, OKF append-log (`type: shortform-decision-log`, newest block on top; format above).
+- `02-DOCS/raw/shortform/metrics.csv` — the per-post ledger (schema in `references/learning-loop-template.md`). This is `raw/`, not `wiki/` — a CSV, no frontmatter.
 
-Verify a produced strategy doc with `scripts/verify.sh 02-DOCS/wiki/shortform/strategy.md` — a read-only structural lint (positioning, cadence, completion KPI, ride-or-skip rule, ≥1 dated decision, sends/saves logged).
+Verify a produced strategy doc with `scripts/verify.sh 02-DOCS/wiki/shortform/strategy.md` — a read-only structural lint (positioning, cadence, completion KPI, ride-or-skip rule, ≥1 dated decision, sends/saves logged). The lint reads body content, so the added frontmatter does not affect it.

package/skills/shortform-strategy/references/learning-loop-template.md

@@ -38,9 +38,17 @@ Run once a month, reading `02-DOCS/raw/shortform/metrics.csv`:
 
 ## Decision-record template
 
-Append to `02-DOCS/wiki/shortform/decisions.md`. Every block is dated, rests on a named metric, and carries a revisit date so it is an experiment, not folklore.
+`02-DOCS/wiki/shortform/decisions.md` is an OKF v0.1 append-log: the frontmatter header (a non-empty `type` is the only OKF hard requirement; `title`/`tags`/`timestamp` are recommended) is written once, then each new block is **prepended newest-first** under the H1. Every block is dated (ISO 8601), rests on a named metric, and carries a revisit date so it is an experiment, not folklore. Past blocks are immutable; bump the header `timestamp` on each append.
 
 ```markdown
+---
+type: shortform-decision-log
+title: Shortform strategy decisions
+tags: [shortform, strategy, decisions]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+---
+# Shortform strategy decisions
+
 ## YYYY-MM-DD — <short decision title>
 **Decision:** <what changes, concretely — cadence/positioning/series/trend rule>
 **Rationale:** <the one-line why>

package/skills/specify/references/spec-template.md

@@ -6,10 +6,21 @@ endpoint, library, file path, or algorithm. If you can't phrase it without
 naming the tech, it's a *point to clarify*, not a requirement.
 
 ```markdown
+---
+type: spec
+title: Spec — <Feature name>
+description: WHAT and WHY for <feature> — problem, goals, behaviour, acceptance criteria.
+tags: [sdd, spec]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: sdd
+slug: <slug>
+status: draft
+---
+
 # Spec — <Feature name>
 
 > Slug: `<slug>` · Status: draft · Created: <YYYY-MM-DD>
-> Inherits: 02-DOCS/wiki/sdd/constitution.md
+> Inherits: [constitution](../constitution.md)
 
 ## Problem & why
 <The pain, who feels it, and the cost of leaving it unsolved. One short

package/skills/tiktok-api/SKILL.md

@@ -251,10 +251,14 @@ A pull that prints to stdout and vanishes is wasted. **Every pull appends a date
 
 Filenames carry the `tiktok-` prefix because the same `shortform/` wiki may also hold Instagram and YouTube pulls — namespacing keeps platforms from colliding.
 
-Per-pull entry template:
+Per-pull entry template. The frontmatter is **OKF v0.1 conformant** — a non-empty `type` is the only hard requirement; `title`/`tags`/`timestamp` are the recommended OKF surface; the domain `date`/`range`/`account`/`platform`/`source` keys the siblings parse are preserved additively (OKF tolerates extra keys). `date` is the reporting day; `timestamp` is the ISO 8601 write moment:
 
 ```markdown
 ---
+type: shortform-metrics
+title: TikTok account snapshot — 2026-06-02
+tags: [tiktok, metrics, snapshot]
+timestamp: 2026-06-02T09:00:00Z
 date: 2026-06-02
 range: 2026-05-26..2026-06-01
 account: <open_id>
@@ -274,7 +278,7 @@ For You 71% · Personal profile 14% · Search 7%
 completion +3.1pts after the tighter cold-open; FYP share up 5pts.
 ```
 
-Rule: **append, never overwrite.** The feedback log *is* the value — overwriting yesterday's snapshot destroys the trend the siblings need, and erases the 24–48h settling you only see across pulls. Exact file tree, naming, and how siblings read the log: `references/wiki-schema.md`.
+Rule: **append, never overwrite.** The feedback log *is* the value — overwriting yesterday's snapshot destroys the trend the siblings need, and erases the 24–48h settling you only see across pulls. The per-video log (`videos/tiktok-<id>.md`) is an OKF append-log: write its frontmatter header once, prepend each new dated block newest-first, never edit a past block. `index.md` is the OKF reserved file — no frontmatter, standard markdown links only. Exact file tree, frontmatter, naming, and how siblings read the log: `references/wiki-schema.md`.
 
 ## 6. Rate & failure math