@ericrisco/rsc 0.1.34 → 0.1.36

package/skills/youtube-api/SKILL.md

@@ -215,10 +215,15 @@ A pull that prints to stdout and vanishes is wasted. **Every pull appends a date
   videos/<VIDEO_ID>.md      # per-video running log, newest entry on top
 ```
 
-Per-pull entry template:
+Per-pull entry template (OKF v0.1: non-empty `type` + the domain keys siblings parse):
 
 ```markdown
 ---
+type: youtube-metrics
+title: Channel snapshot 2026-05-31
+description: Channel KPIs, traffic and retention for 2026-05-01..2026-05-31.
+tags: [youtube, channel-snapshot]
+timestamp: 2026-05-31T00:00:00Z
 date: 2026-05-31
 range: 2026-05-01..2026-05-31
 channel: MINE
@@ -237,7 +242,7 @@ Sharp drop 0.00→0.06 (intro), recovers, second dip ~0.55.
 avg_view_pct +2.1pts; SUGGESTED share up 6pts after the Ep.13 packaging change.
 ```
 
-Rule: **append, never overwrite.** The feedback log *is* the value — overwriting yesterday's snapshot destroys the trend the siblings need. 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. `02-DOCS/wiki/` is an OKF v0.1 bundle: keep the domain keys (`date`, `range`, `channel`, `source`) the siblings parse, add `type`/`timestamp` alongside them, use standard markdown links (never `[[wikilinks]]`), and leave the reserved `index.md` frontmatter-free. Exact file tree, naming, per-video log shape, and how siblings read the log: `references/wiki-schema.md`.
 
 ## 7. Quota & failure math
 

package/skills/youtube-api/references/wiki-schema.md

@@ -2,6 +2,8 @@
 
 The point of this skill is not to print stats once; it is to grow a **feedback log** the strategy/packaging siblings can read. The log lives under `02-DOCS/wiki/youtube/` and every pull **appends** to it.
 
+`02-DOCS/wiki/` is an **OKF v0.1** bundle, so every non-reserved `.md` file written here carries YAML frontmatter with a non-empty `type`. This skill writes `type: youtube-metrics` on its snapshots/logs and keeps the domain keys (`date`, `range`, `channel`, `source`) that the strategy/packaging siblings parse literally — `type` and `timestamp` are added *alongside* them, never replacing them. OKF allows arbitrary extra keys, so the shared keys stay stable. Links between wiki files are standard markdown links (`[text](./file.md)`), never Obsidian wikilinks.
+
 ## File tree
 
 ```text
@@ -24,6 +26,11 @@ Naming:
 
 ```markdown
 ---
+type: youtube-metrics
+title: Channel snapshot 2026-05-31
+description: Channel KPIs and traffic for 2026-05-01..2026-05-31.
+tags: [youtube, channel-snapshot]
+timestamp: 2026-05-31T00:00:00Z
 date: 2026-05-31
 range: 2026-05-01..2026-05-31
 channel: MINE
@@ -40,9 +47,20 @@ BROWSE 44% · SUGGESTED 31% · YT_SEARCH 12%
 avg_view_pct +2.1pts; SUGGESTED share +6pts after the Ep.13 packaging change.
 ```
 
-## Per-video entry template (prepended to `videos/<id>.md`)
+## Per-video log file — `videos/<VIDEO_ID>.md`
+
+The file carries frontmatter once (at the top); each new dated block is **prepended directly under the frontmatter** (newest entry first — this is an append-log, past entries are immutable). On the first write, create the frontmatter; on every later pull, refresh `timestamp` and insert the new block above the previous newest one. Keep the domain key `channel` so siblings can parse it.
 
 ```markdown
+---
+type: youtube-metrics
+title: Video log — dQw4w9WgXcQ
+description: Per-pull KPI/traffic/retention log for video dQw4w9WgXcQ, newest entry first.
+tags: [youtube, video-log]
+timestamp: 2026-05-31T00:00:00Z
+channel: MINE
+source: youtube-analytics-api-v2
+---
 ## 2026-05-31  (range 2026-05-01..2026-05-31)
 views: 8,902 | avg_view_pct: 41.0% | ctr(studio): 6.2%
 traffic: SUGGESTED 52% · BROWSE 23% · YT_SEARCH 9%
@@ -52,10 +70,12 @@ note: held suggested-traffic share week over week.
 
 ## index.md
 
+OKF **reserved file**: a directory listing, so it carries **no frontmatter**. Point at the latest snapshot and tracked videos with standard markdown links (never wikilinks).
+
 ```markdown
 # YouTube channel feedback log
-latest snapshot: channel-2026-05-31.md
-videos tracked: dQw4w9WgXcQ, abc123XYZ
+latest snapshot: [channel-2026-05-31.md](./channel-2026-05-31.md)
+videos tracked: [dQw4w9WgXcQ](./videos/dQw4w9WgXcQ.md), [abc123XYZ](./videos/abc123XYZ.md)
 
 ## Open questions for strategy/packaging
 - Intro drop-off at 0.06 recurs across last 3 uploads — packaging or pacing?
@@ -67,4 +87,5 @@ videos tracked: dQw4w9WgXcQ, abc123XYZ
 1. **Append, never overwrite.** A snapshot is a point in time; deleting it erases the trend. The history is the deliverable.
 2. **One source of truth for derived numbers.** Store what the API returned. Mark Studio-sourced values explicitly (`ctr(studio)`) so a reader knows it was not API-derived.
 3. **No interpretation in the log beyond a one-line "what changed."** Deeper reading ("we should change the hook") is the strategy/packaging sibling's job — this skill records, it does not prescribe.
-4. **Siblings read this tree.** Keep frontmatter keys stable (`date`, `range`, `channel`, `source`) so a sibling can parse the latest snapshot without guessing.
+4. **Siblings read this tree.** Keep the domain frontmatter keys stable (`date`, `range`, `channel`, `source`) so a sibling can parse the latest snapshot without guessing. The OKF keys (`type`, `title`, `description`, `tags`, `timestamp`) are added alongside them, never instead of them — all four youtube skills share this same key set and the same markdown-link style.
+5. **OKF-conformant wiki content.** Every non-reserved `.md` here has a non-empty `type` (`youtube-metrics`). `index.md` is the lone reserved file (no frontmatter, a directory listing). Per-video logs are newest-first append-logs with ISO 8601 dates; past dated blocks are never edited. Cross-references use standard markdown links (`[text](./file.md)`), never `[[wikilinks]]`.

package/skills/youtube-packaging/SKILL.md

@@ -46,7 +46,13 @@ produce generic copy in someone else's voice.
   hook, the keyword, and the audience all at once.)
 
 Persist what you write under `02-DOCS/wiki/youtube/` (the package) and raw test
-results under `02-DOCS/raw/youtube/`.
+results under `02-DOCS/raw/youtube/`. `02-DOCS/wiki/` is an **OKF v0.1** bundle:
+every package or log file persisted there carries YAML frontmatter with a
+non-empty `type` (`youtube-package`) plus the OKF surface (`title`, `description`,
+`tags`, `timestamp`) shared with the strategy/thumbnail/api siblings, and all
+cross-references use standard markdown links — never `[[wikilinks]]`. The OKF
+frontmatter shape for the persisted package and log is in
+[references/description-and-chapters.md](references/description-and-chapters.md).
 
 ## The title
 
@@ -158,7 +164,9 @@ carry forward what won as priors: if numeric titles beat curiosity titles 3 test
 running on this channel, the new set leans numeric. If a hashtag set tanked, drop
 it.
 
-**Append after you test.** One row per test:
+**Append after you test.** One row per test, into `02-DOCS/wiki/youtube/packaging-log.md`
+(OKF v0.1: file-level `type: youtube-package` frontmatter at the top, the table
+below it, newest rows appended, past rows immutable):
 
 ```text
 | date | video | title set tried | winner | CTR | impressions | avg view duration | note |

package/skills/youtube-packaging/references/description-and-chapters.md

@@ -1,8 +1,9 @@
 # Description, chapters & feedback-log formats
 
-Offloaded depth for [../SKILL.md](../SKILL.md). Three things live here: the full
+Offloaded depth for [../SKILL.md](../SKILL.md). Four things live here: the full
 description template with a filled example, the chapter format spec with the four
-failure cases worked through, and the feedback-log entry schema with a filled row.
+failure cases worked through, the feedback-log entry schema with a filled row, and
+the OKF v0.1 frontmatter shape for the package and log when persisted into the wiki.
 
 ## 1. Description template
 
@@ -110,6 +111,31 @@ should be short and scannable — it doubles as a search jump-to target.
 One markdown table in `02-DOCS/wiki/youtube/packaging-log.md`. One row per A/B
 test, appended when Test & Compare resolves (~2 weeks).
 
+`02-DOCS/wiki/` is an **OKF v0.1** bundle, so `packaging-log.md` carries
+file-level frontmatter once at the top (a non-empty `type` plus the OKF surface
+shared across all four youtube skills), then the table below it. Refresh
+`timestamp` when you append a row; past rows are immutable.
+
+```markdown
+---
+type: youtube-package
+title: Packaging feedback log
+description: One row per Test & Compare result — title sets tried, winner, and the transferable lesson.
+tags: [youtube, packaging-log, ab-testing]
+timestamp: 2026-05-28T00:00:00Z
+---
+# Packaging feedback log
+
+| date | video | title set tried | winner | CTR | impressions | avg view duration | note |
+|------|-------|-----------------|--------|-----|-------------|-------------------|------|
+```
+
+> Note: this frontmatter is for the **persisted wiki file**. The package *draft*
+> you point `scripts/verify.sh` at uses labeled sections (`Titles:`,
+> `Description:`, …) and stays frontmatter-free so the linter parses it cleanly.
+
+Column meanings:
+
 | Column | Meaning |
 |---|---|
 | `date` | resolution date of the test (YYYY-MM-DD) |
@@ -133,3 +159,45 @@ The `note` column is the point: it turns one data row into a prior the next
 package carries forward. Always grade the winner by watched-time-per-impression
 (reflected in CTR *and* avg view duration together), never CTR alone — a high-CTR /
 low-duration row is a warning, not a win.
+
+## 4. Persisted package — the wiki file
+
+When you persist a finished package under `02-DOCS/wiki/youtube/` (e.g.
+`packages/<video-slug>.md`), wrap it in OKF v0.1 frontmatter — a non-empty `type`
+plus the shared OKF surface — so the wiki bundle stays conformant and the
+strategy/thumbnail siblings can read it. The body holds the human-readable
+package; cross-references use standard markdown links, never `[[wikilinks]]`.
+
+```markdown
+---
+type: youtube-package
+title: Package — Learn Python in 2026 (beginner tutorial)
+description: Title set, description, tags, hashtags and chapters for the 12-minute beginner Python tutorial.
+tags: [youtube, packaging]
+timestamp: 2026-05-28T00:00:00Z
+---
+# Package — Learn Python in 2026 (beginner tutorial)
+
+## Titles (A/B set)
+- Learn Python in 2026: 12-Min Beginner Tutorial
+- Python in 12 Minutes (Total Beginner)
+- I Taught a Beginner Python in 12 Min
+
+## Description
+<above-fold line + body + links + hashtag line, per §1>
+
+## Tags
+python, learn python, python tutorial, python for beginners, …
+
+## Hashtags
+#Python #LearnToCode #ProgrammingForBeginners
+
+## Chapters
+00:00 Intro — what you'll build
+…
+```
+
+> The `scripts/verify.sh` linter runs on the package **draft** (labeled sections,
+> no frontmatter). The persisted wiki file adds the frontmatter above the same
+> body — do not feed the frontmatter'd wiki copy to the linter, since its `tags:`
+> frontmatter key would be read as the Tags section.

package/skills/youtube-strategy/SKILL.md

@@ -128,14 +128,21 @@ Read CTR (>~6% is healthy for new channels) and AVD/retention from the wiki to c
 A strategy session that does not write back does not compound — the next session starts from zero. On exit, append a **dated decision record** under `02-DOCS/wiki/youtube/` and, when reviewing, a **what-worked** entry tied to specific videos/playlists. Minimal record inline; full templates in `references/wiki-records.md`:
 
 ```markdown
+---
+type: youtube-strategy-record
+title: Niche down to budget mechanical keyboards for programmers
+description: Reposition from broad tech reviews to budget mechanical keyboards for programmers; hold 2/wk cadence.
+tags: [youtube, strategy-decision, positioning]
+timestamp: 2026-06-02T00:00:00Z
+---
 # 2026-06-02 — Niche down to budget mechanical keyboards for programmers
-- Context read: flat subs at 40 videos; top 3 by AVD all keyboard reviews (wiki/youtube/what-worked.md)
+- Context read: flat subs at 40 videos; top 3 by AVD all keyboard reviews ([what-worked.md](./what-worked.md))
 - Decision: reposition from "tech reviews" to "budget mechanical keyboards for programmers"; cadence 2/wk held
 - Bets on metric: AVD on keyboard videos (currently ~48%) holding while non-keyboard topics are dropped
 - Review date: 2026-09-02
 ```
 
-Every record names **the metric it is betting on** and a **review date**. A decision with no metric is an opinion, not a bet you can later check. Run `scripts/verify.sh 02-DOCS/wiki/youtube/` after writing to confirm the records are structurally complete.
+`02-DOCS/wiki/` is an OKF v0.1 bundle: every record carries a non-empty `type` (`youtube-strategy-record`) above the body, and cross-references use standard markdown links (never `[[wikilinks]]`). Every record names **the metric it is betting on** and a **review date**. A decision with no metric is an opinion, not a bet you can later check. Run `scripts/verify.sh 02-DOCS/wiki/youtube/` after writing to confirm the records are structurally complete (date, `Decision:`, metric, and `type`). Full templates in `references/wiki-records.md`.
 
 ## Anti-patterns
 

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

@@ -2,6 +2,8 @@
 
 This is where the channel's strategy memory lives. The skill READs it on entry and WRITEs to it on exit so sessions compound. Keep it append-only.
 
+`02-DOCS/wiki/` is an **OKF v0.1** bundle, so every `.md` record this skill writes carries YAML frontmatter with a non-empty `type` (`youtube-strategy-record`) plus the OKF surface (`title`, `description`, `tags`, `timestamp`). These are shared, identically, across all four youtube skills. The strategy-specific body fields the loop and `verify.sh` rely on (`Decision:`, `Bets on metric:`, the date) stay in the body exactly as before — the frontmatter is purely additive. All cross-references use standard markdown links (`[text](./file.md)`), never `[[wikilinks]]`.
+
 ## File layout under `02-DOCS/wiki/youtube/`
 
 ```text
@@ -28,6 +30,13 @@ mkdir -p 02-DOCS/wiki/youtube/decisions
 `positioning.md` stub:
 
 ```markdown
+---
+type: youtube-strategy-record
+title: Channel positioning
+description: The channel's current niche, who-it's-for, and three-factor rationale.
+tags: [youtube, positioning]
+timestamp: 2026-06-02T00:00:00Z
+---
 # Channel positioning
 - Niche: <to define — narrow 2-3 levels, not an industry>
 - Who it's for: <specific viewer>
@@ -37,11 +46,18 @@ mkdir -p 02-DOCS/wiki/youtube/decisions
 
 ## Decision-record template
 
-Every decision file carries these fields. The metric line is mandatory — a decision with no metric is an opinion, not a checkable bet.
+Every decision file carries the frontmatter (`type` + OKF surface) **and** these body fields. The metric line is mandatory — a decision with no metric is an opinion, not a checkable bet. The body fields (`Decision:`, `Bets on metric:`, the date) are what `verify.sh` lints, so keep them verbatim; the frontmatter sits above them.
 
 ```markdown
+---
+type: youtube-strategy-record
+title: <one-line decision title>
+description: <one-sentence summary of the decision and what it bets on>
+tags: [youtube, strategy-decision]
+timestamp: <YYYY-MM-DDTHH:MM:SSZ>
+---
 # <YYYY-MM-DD> — <one-line decision title>
-- Context read: <what the wiki/data said that drove this; cite files>
+- Context read: <what the wiki/data said that drove this; cite files with markdown links>
 - Decision: <positioning / cadence / series choice, stated concretely>
 - Bets on metric: <the single metric this decision expects to move, with current value>
 - Review date: <YYYY-MM-DD — when to check whether the bet paid off>
@@ -50,8 +66,15 @@ Every decision file carries these fields. The metric line is mandatory — a dec
 Worked example:
 
 ```markdown
+---
+type: youtube-strategy-record
+title: Niche down to budget mechanical keyboards for programmers
+description: Reposition from broad tech reviews to budget mechanical keyboards for programmers, holding 2/wk cadence.
+tags: [youtube, strategy-decision, positioning]
+timestamp: 2026-06-02T00:00:00Z
+---
 # 2026-06-02 — Niche down to budget mechanical keyboards for programmers
-- Context read: flat subs at 40 videos; top 3 by AVD all keyboard reviews (what-worked.md)
+- Context read: flat subs at 40 videos; top 3 by AVD all keyboard reviews ([what-worked.md](../what-worked.md))
 - Decision: reposition from "tech reviews" to "budget mechanical keyboards for programmers"; hold cadence 2/wk
 - Bets on metric: AVD on keyboard videos (~48%) holds while non-keyboard topics are dropped
 - Review date: 2026-09-02
@@ -59,15 +82,24 @@ Worked example:
 
 ## What-worked template
 
-Append one entry per observed win or loss, tied to a real asset so future sessions can pattern-match.
+`what-worked.md` carries the file-level frontmatter once at the top; below it, **append one entry per observed win or loss** (append-only, ISO 8601 dates, past entries immutable), tied to a real asset so future sessions can pattern-match. Refresh `timestamp` when you append.
 
 ```markdown
+---
+type: youtube-strategy-record
+title: What worked — wins and losses log
+description: Running log of channel wins/losses tied to specific videos and playlists.
+tags: [youtube, what-worked]
+timestamp: 2026-05-20T00:00:00Z
+---
+# What worked
+
 ## <YYYY-MM-DD> — <video or playlist id/title>
 - Metric: <CTR / AVD / session lift, with the number>
 - Lesson: <the transferable insight — what to do more or less of>
 ```
 
-Example:
+Example entry (appended under the frontmatter + heading):
 
 ```markdown
 ## 2026-05-20 — "I Tested 5 Sub-$20 Keyboards" (vid abc123)
@@ -82,5 +114,6 @@ Example:
 1. The target `02-DOCS/wiki/youtube/` directory exists.
 2. At least one decision record is present (a `decisions/*.md` file or a `decisions.md` log).
 3. Each decision record contains the three required signals: a date, a `Decision:` line, and a named metric/bet (a `Bets on metric:` line or equivalent `metric`/`bet` field).
+4. Each decision record carries a non-empty `type:` frontmatter field (the OKF v0.1 conformance check). A record with no `type` is a hard failure.
 
-A record missing the metric field is a hard failure with a clear message. An empty or missing target reports cleanly and exits 0 — no false failure on a fresh channel.
+A record missing the metric or `type` field is a hard failure with a clear message. An empty or missing target reports cleanly and exits 0 — no false failure on a fresh channel. The `type` check is additive: it does not touch the existing date/`Decision:`/metric checks.

package/skills/youtube-strategy/scripts/verify.sh

@@ -13,6 +13,8 @@
 #          - a named metric/bet (a "Bets on metric:" / "metric" / "bet" field)
 #        A record missing the metric/bet field is a HARD FAILURE — a decision with
 #        no metric is an opinion, not a checkable bet.
+#     4. Each decision record carries a non-empty `type:` frontmatter field
+#        (OKF v0.1 conformance). A record with no `type` is a HARD FAILURE.
 #
 #   Missing date or Decision line is also a hard failure. A missing/empty target
 #   (a fresh channel with no wiki yet) is reported and exits 0 — no false failure.
@@ -105,6 +107,8 @@ while IFS= read -r rec; do
   grep -Eq "$DATE_RE"                    "$rec" || miss="$miss date"
   grep -Eiq '^[[:space:]-]*Decision:'    "$rec" || miss="$miss decision-line"
   grep -Eiq '(bets on metric:|metric|bet:)' "$rec" || miss="$miss metric/bet"
+  # OKF v0.1: a non-empty `type:` frontmatter field is required.
+  grep -Eiq '^[[:space:]]*type:[[:space:]]*[^[:space:]]' "$rec" || miss="$miss type"
 
   if [ -n "$miss" ]; then
     fail "$rec: missing required field(s):$miss"

package/skills/youtube-thumbnails/SKILL.md

@@ -125,17 +125,22 @@ the video doesn't cash. That is a promise problem, not an image problem.
 ## The feedback loop (wiki)
 
 Every test result goes to the channel wiki. Exact path:
-`02-DOCS/wiki/youtube/`.
+`02-DOCS/wiki/youtube/`. `02-DOCS/wiki/` is an **OKF v0.1** bundle: both files
+below carry file-level frontmatter with a non-empty `type` (`thumbnail-experiment`)
+plus the OKF surface (`title`, `description`, `tags`, `timestamp`) shared with the
+api/strategy/packaging siblings, and cross-references use standard markdown links,
+never `[[wikilinks]]`.
 
-**Log file** — `thumbnail-experiments.md`, one row per test:
+**Log file** — `thumbnail-experiments.md`, frontmatter at the top then one row per
+test (append-only, ISO 8601 dates, past rows immutable):
 
 ```text
 | date | video | variants | axis tested | winner | CTR | watch-time share | note |
 ```
 
-**Derived file** — `thumbnail-patterns.md`, a running table of what wins on THIS
-channel (e.g. "faces beat objects 4/5 tests", "no-text wins on tutorials"). You
-update this after each logged test.
+**Derived file** — `thumbnail-patterns.md`, frontmatter at the top then a running
+table of what wins on THIS channel (e.g. "faces beat objects 4/5 tests", "no-text
+wins on tutorials"). You update this after each logged test.
 
 **Next-concept rule:** the next thumbnail keeps the winning level of every axis
 already settled by the log, and tests the next unsettled axis. You only re-test a

package/skills/youtube-thumbnails/references/experiment-log-format.md

@@ -3,6 +3,14 @@
 The wiki layout, schema, filled example, and pattern-mining heuristic for the
 feedback loop in SKILL.md. Everything lives under `02-DOCS/wiki/youtube/`.
 
+`02-DOCS/wiki/` is an **OKF v0.1** bundle, so both files below carry file-level
+YAML frontmatter with a non-empty `type` (`thumbnail-experiment`) plus the OKF
+surface (`title`, `description`, `tags`, `timestamp`) — the same shared key set the
+api/strategy/packaging siblings use. The frontmatter sits once at the top of each
+file, above the table. Refresh `timestamp` when you append/rewrite. Any
+cross-reference uses a standard markdown link (`[text](./file.md)`), never an
+Obsidian `[[wikilink]]`.
+
 ## Files
 
 - `thumbnail-experiments.md` — append-only log, one row per Test & Compare run.
@@ -11,7 +19,18 @@ feedback loop in SKILL.md. Everything lives under `02-DOCS/wiki/youtube/`.
 
 ## `thumbnail-experiments.md` schema
 
-```text
+File-level frontmatter once at the top, then the append-only table below it:
+
+```markdown
+---
+type: thumbnail-experiment
+title: Thumbnail experiments log
+description: One row per Test & Compare run — variants, axis tested, winner, and the takeaway.
+tags: [youtube, thumbnails, ab-testing]
+timestamp: 2026-06-01T00:00:00Z
+---
+# Thumbnail experiments
+
 | date | video | variants | axis tested | winner | CTR | watch-time share | note |
 ```
 
@@ -38,7 +57,14 @@ feedback loop in SKILL.md. Everything lives under `02-DOCS/wiki/youtube/`.
 
 ## `thumbnail-patterns.md` shape
 
-```text
+```markdown
+---
+type: thumbnail-experiment
+title: What wins on this channel
+description: Derived summary of the settled thumbnail axes and their confidence.
+tags: [youtube, thumbnails, patterns]
+timestamp: 2026-06-01T00:00:00Z
+---
 # What wins on this channel
 
 | axis | settled winner | evidence | confidence |