docs: add buildstream skill for factory-wide BST patterns

[castrojo]

What

Adds docs/skills/buildstream/ — a factory-level skill capturing the BuildStream 2 patterns that are true for every factory BST repo (today: dakota and fsdk-containers), harvested from both repos' docs/skills/.

• SKILL.md — scope rule, the per-repo divergence table, 7 core patterns, red flags, verification
• references/cache-keys-and-junctions.md — strong/weak key model, invalidation cones, junction drift-control policy
• references/element-authoring.md — element/source kinds, dependency types, variables, conditionals, sandbox constraints, overlap rules
• Registered in docs/SKILL.md router; index.json/index.md regenerated; /apache/buildstream added to the known Context7 IDs in context7.md

Junction patch queues: drift control, not "never patch"

A junction's patch_queue is part of its source hash, so the queue determines which upstream artifact cache your keys align with:

• Patches diverging from the parent project's own queue are cache-destroying → prohibited.
• Patches replicating the parent's queue byte-for-byte at the pinned ref are cache-aligning → mandatory when the parent carries one.
• The enforceable rule is drift control against the parent's queue (dakota: just patch-drift-check in CI); the per-repo parameter is which upstream queue to match (currently gnome-build-meta at the pinned ref in both repos).

Note: dakota's own docs/skills/patch-junctions.md states an absolute "NO LOCAL JUNCTION PATCH QUEUES" rule that is contradicted by dakota's current state (patches/freedesktop-sdk/ carries 0001–0007) and by its own bst-overrides.md (byte-identity requirement). That inconsistency is reported for correction at the source in dakota — this skill deliberately does NOT repeat the absolute rule.

The general-vs-repo-specific line

Promoted only what holds in both repos. Explicitly documented as per-repo decisions, not factory rules:

Decision	dakota	fsdk-containers
Composition	bootable OS, platform content in scope	components/* only, platform.bst banned
Micro-arch	opt-in x86_64_v3	banned (broad-compat baseline)
Output	bootc OS (systemd/shell/dconf/ldconfig)	distroless, no shell, SLIM + just verify

Not promoted: dakota's packaging templates (packaging-*.md), systemd/preset/dconf/bootc-ldconfig rules, GNOME/GL specifics; fsdk-containers' SLIM recipe, no-shell rule, verify gates, FSDK-tag versioning.

Evidence

• BST behavior verified via Context7 /apache/buildstream (arch_cachekeys.md, format_public.md, format_project.md, handling-files/composition.md, downloadablefilesource.py); cited inline.
• Repo claims verified against source: project.conf options in both repos, fsdk integration/ldconfig.bst usage, dakota elements/freedesktop-sdk.bst v3 conditional, both repos' junction patch queues.
• pre-commit run --all-files green (front-matter, index staleness, doc links).

Docs-only change (docs/**); opened as draft for review per factory PR policy.

[hanthor]

Needs a rebase — the generated skill index in this branch is 9 days behind main

Still a draft, so this is informational rather than a gate. The content itself is docs-only and validate was green when it last ran, but the branch no longer merges:

$ git merge pr979
Auto-merging docs/skills/context7.md
CONFLICT (content): Merge conflict in docs/skills/index.json
CONFLICT (content): Merge conflict in docs/skills/index.md

Both conflicts are in generated files, and both are the same stale-date problem. This branch carries:

-  "generated_at": "2026-08-08",
+  "generated_at": "2026-08-09",

while main has moved on:

$ head -2 docs/skills/index.json
{
  "generated_at": "2026-08-18",
$ grep -n "^Generated" docs/skills/index.md
6:Generated: 2026-08-18 · schema 1.0 · 40 skills

So the index edits here were stale the moment main regenerated, and hand-resolving them risks reverting main's index by 9 days and one skill entry.

The fix is mechanical and the repo already has the tool for it — after rebasing, drop both index files from the diff and regenerate:

python3 scripts/generate_skill_index.py --write
python3 scripts/generate_skill_index.py --check

--check passes on main today, so a correct rebase should land on docs/skills/index.json and index.md are up to date (41 skills) once buildstream is added.

The substantive part — docs/skills/buildstream/SKILL.md plus the two reference files, and the docs/SKILL.md / docs/skills/context7.md links — is self-contained and low risk: nothing under system_files/, so no image blast radius across bluefin / bluefin-lts / dakota. python3 scripts/check-doc-links.sh passes on main; re-run it after the rebase to confirm the new references/ links resolve.

---

Generated by Claude Code