@r1z4x/tezgah 1.9.0 → 1.11.0

package/hosts/opencode/tui/cli/tui.tsx

@@ -0,0 +1,100 @@
+/** @jsxImportSource @opentui/solid */
+// tezgah status line for the opencode 2 terminal (a CLI plugin).
+//
+// opencode 2 ignores tui.json: a local CLI plugin is a DIRECTORY listed in
+// ~/.config/opencode/cli.json `plugins` (a spec naming a file is skipped), whose
+// `tui` module default-exports Plugin.define({ id, setup }). Same data and marks
+// as ../tezgah-tui.tsx (the opencode 1 shape, kept for v1 installs): one
+// `tezgah-status <dir> --json [sessionID]` call per refresh, each segment colored
+// green in force, yellow on-demand, red off, and a palette command for the legend.
+import { Plugin } from "@opencode/plugin/tui"
+import { createSignal, onCleanup, For } from "solid-js"
+import { run } from "../tezgah-tui.tsx"
+
+const SAFETY_MS = 30000
+// Server events arrive per streamed part; one status call per burst is enough.
+const DEBOUNCE_MS = 250
+
+type Seg = { key: string; state: string; glyph: string; text: string; group?: number }
+type Tone = { base: string }
+// The part of the CLI plugin context this file reads (opencode.ai/v2/docs/build/plugins/cli).
+type Ctx = {
+  location?: { directory?: string }
+  theme: { text: { muted: string; feedback: { success: Tone; warning: Tone; error: Tone } } }
+  data: { location: { default(): { directory?: string } | undefined }; listen(fn: () => void): () => void }
+  ui: { router: { current(): { type: string; sessionID?: string } | undefined } }
+}
+
+function color(ctx: Ctx, state: string) {
+  const t = ctx.theme.text
+  if (state === "on") return t.feedback.success.base
+  if (state === "ready") return t.feedback.warning.base
+  if (state === "off") return t.feedback.error.base
+  return t.muted
+}
+
+function args(ctx: Ctx): string[] {
+  const dir = ctx.location?.directory || ctx.data.location.default()?.directory || process.cwd()
+  // The active session id is what lets the used marks (graph/consult/orch) light.
+  const route = ctx.ui.router.current()
+  return route?.type === "session" && route.sessionID ? [dir, "--json", route.sessionID] : [dir, "--json"]
+}
+
+function TezgahBar(props: { ctx: Ctx }) {
+  const [segs, setSegs] = createSignal<Seg[]>([])
+  const update = () => {
+    try {
+      setSegs(JSON.parse(run(args(props.ctx)) || "[]"))
+    } catch {
+      setSegs([])
+    }
+  }
+  let pending: Timer | undefined
+  const soon = () => {
+    clearTimeout(pending)
+    pending = setTimeout(update, DEBOUNCE_MS)
+  }
+
+  update()
+  const stop = props.ctx.data.listen(soon)
+  const timer = setInterval(update, SAFETY_MS)
+  onCleanup(() => {
+    stop()
+    clearTimeout(pending)
+    clearInterval(timer)
+  })
+
+  return (
+    <box paddingLeft={1} flexShrink={0} flexDirection="row">
+      <For each={segs()}>
+        {(s, i) => (
+          <box flexDirection="row">
+            <text fg={color(props.ctx, s.state)}>{s.text + (s.glyph || "")}</text>
+            <text fg={props.ctx.theme.text.muted}>
+              {i() < segs().length - 1
+                ? (segs()[i() + 1].group === s.group ? " " : "  ·  ")
+                : ""}
+            </text>
+          </box>
+        )}
+      </For>
+    </box>
+  )
+}
+
+export default Plugin.define({
+  id: "tezgah.status",
+  setup(ctx) {
+    ctx.keymap.layer(() => ({
+      mode: "global",
+      commands: [{
+        id: "tezgah.legend",
+        title: "tezgah: status legend",
+        group: "tezgah",
+        palette: true,
+        run: () => ctx.ui.dialog.alert({ title: "tezgah status marks", message: run(["--legend"]) }),
+      }],
+    }))
+    return ctx.ui.slot({ append: "prompt.footer", render: () => <TezgahBar ctx={ctx} /> })
+  },
+})

package/hosts/opencode/tui/tezgah-tui.tsx

@@ -51,7 +51,8 @@ function pythonBin(): string {
   return (pythonMemo = found || names[0])
 }
 
-function run(args: string[]): string {
+// Exported for cli/tui.tsx, the opencode 2 shape of this plugin.
+export function run(args: string[]): string {
   try {
     const proc = Bun.spawnSync({ cmd: [pythonBin(), STATUS, ...args], stdout: "pipe", stderr: "ignore" })
     return new TextDecoder().decode(proc.stdout).trim()

package/output-styles/tezgah.md

@@ -36,7 +36,7 @@ one small test); a one-liner needs none. A complex ask ships the lazy version
 and names the fuller one in the same reply instead of stalling. Reply: code
 first; write what was cut only when you consciously cut something the user asked
 for, in at most three lines. In force from the first turn; levels
-lite|full|ultra are set with `tezgah-pony` and ride the per-turn reminder when
+lite|full|ultra are set with `~/.config/tezgah/bin/tezgah-pony` and ride the per-turn reminder when
 not `full`; read the full `ponytail` skill from the router for the level table
 and examples. Off: "stop ponytail".
 
@@ -62,7 +62,7 @@ assumption and ask one diagnostic question. Before sending, delete an opening
 sentence that announces, a closing one that recaps or asks "anything else?", any
 by-the-way sidebar and any hedge that carries no real uncertainty. In force from
 the first answer; read the full `i-have-adhd` skill from the router for the
-examples. Off: `tezgah-adhd off`, or the repo's `.no-adhd`.
+examples. Off: `~/.config/tezgah/bin/tezgah-adhd off`, or the repo's `.no-adhd`.
 
 **Deliver the whole ask; never the shortcut.** The request defines the
 deliverable: every named item is in scope until the user says otherwise, and the
@@ -169,19 +169,19 @@ issue for one of its tools mid-session. Name a missing capability in one line,
 use the documented fallback (grep/find, or the second opinion skipped), and carry
 on with the task in hand. Tezgah maintenance is in scope when the user asks for
 it, or when the repo IS the tezgah checkout. Before working a topic an
-installed skill covers, run `tezgah-skill <words>` and read only the range it
+installed skill covers, run `~/.config/tezgah/bin/tezgah-skill <words>` and read only the range it
 returns.
 
 **Workspace: `.tezgah/` only.** Every per-project tezgah artifact - plans,
-research lines, analysis, lessons - lives under `<repo>/.tezgah/`, which the
-project's `.gitignore` excludes and which keeps its own private git repository
-(`git -C .tezgah ...`). Never create `plans/`, `research/` or `analysis/` at the
-project root and never `git add -f` anything under `.tezgah/`. Off:
+research lines, analysis, lessons - lives under `<repo>/.tezgah/`, ignored by
+the project, committed with `git -C .tezgah ...` - or, if the project tracks
+it, plain `git add`/`git commit`. Never create `plans/`, `research/` or
+`analysis/` at the project root and never `git add -f` under `.tezgah/`. Off:
 `workspace-off`.
 
 **Kill switches:** each one removes its own rule from this text, not just the
 status mark. `~/.config/tezgah/`: `exec-mode.off`, `orchestrate-off`,
-`consult-off`, `research-off`, `ponytail-auto.off`, `adhd-off`, `spec-off`,
+`consult-off`, `research-off`, `ponytail-auto.off`, `adhd-off`, `spec-off`, `design-off`,
 `reminder-off`, `verify-off` (the integrity rule: its prompt text, the shortcut
 denials and the Stop gate), `task-off` (the task rule), `judge-off` (the
 judgement seam: the triage, the docs fallback and the skill hint), `triage-off`,
@@ -189,6 +189,6 @@ judgement seam: the triage, the docs fallback and the skill hint), `triage-off`,
 rule), `workspace-off` (the root plans/research/analysis refusal),
 `pretooluse-off` (the whole gate);
 per-repo `.no-ponytail`, `.no-adhd`, `.no-graph`, `.no-lessons`.
-The ponytail intensity level is not a switch: `tezgah-pony lite|full|ultra`.
+The ponytail intensity level is not a switch: `~/.config/tezgah/bin/tezgah-pony lite|full|ultra`.
 
-**On-demand rules (armed when the task class matches; full text in the `tezgah-contract` skill).** Spec-first for an underspecified or quality-only ask. A second opinion before a call that is hard to reverse or that one model would answer with unearned confidence. OpenResearch routing for research. Product analysis is a five-axis evidence task - value, usability (the running app, not the source), feasibility (a cited `path:line`), competition, and keep/fix/cut/bet triage - with one named evidence class per finding. The code graph for "who calls X" and "what breaks if Z changes". Two or more independent items fan out to parallel subagents in one message, one git worktree per writing slice. The design floor a UI turn is judged against is `.tezgah/design-contract.md`: `tezgah-design derive` writes it from the repository's own tokens, `tezgah-design check` measures a change against it, and the `design-contract` skill owns its shape.
+**On-demand rules (armed when the task class matches; full text in the `tezgah-contract` skill).** Spec-first for an underspecified or quality-only ask. A second opinion before a call that is hard to reverse or that one model would answer with unearned confidence. OpenResearch routing for research. Product analysis is a five-axis evidence task - value, usability (the running app, not the source), feasibility (a cited `path:line`), competition, and keep/fix/cut/bet triage - with one named evidence class per finding (`product-analysis`, `pm-frameworks`). The code graph for "who calls X" and "what breaks if Z changes". Two or more independent items fan out to parallel subagents in one message, one git worktree per writing slice. A UI turn reads the `design-contract` skill (`design-library`, `analyze-app`) and is judged against `.tezgah/design-contract.md`: `~/.config/tezgah/bin/tezgah-design derive` writes it from the repository's own tokens and its `check` measures a change against it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r1z4x/tezgah",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "One shared working contract for every AI coding assistant you run: Claude Code, Codex, Cursor, opencode, dsh and oh-my-pi (omp).",
   "license": "MIT",
   "repository": {

package/packaging/install.ps1

@@ -27,6 +27,11 @@
 
       $env:TEZGAH_VERSION = '0.1.0'; irm https://raw.githubusercontent.com/r1z4x/tezgah/main/packaging/install.ps1 | iex
 
+  The tezgah repository is private, so that fetch and the release below need a
+  token with read access, in `TEZGAH_GITHUB_TOKEN`, `GITHUB_TOKEN` or `GH_TOKEN`:
+
+      $env:GITHUB_TOKEN = 'ghp_...'
+
 .EXAMPLE
   .\install.ps1 -Version 0.1.0 -Prefix D:\tezgah
 #>
@@ -59,16 +64,29 @@ function Remove-Current([string]$Path) {
 }
 
 if ($env:TEZGAH_REPO) { $Repo = $env:TEZGAH_REPO }
+# A private repository serves no release file to an anonymous session, so the
+# token decides which URL is read: the REST asset endpoint with it, the plain
+# download URL without. `releases/download/...` answers 404 to both a token in
+# the URL and a bearer header (measured 2026-10-17), so the id comes first.
+$Token = $env:TEZGAH_GITHUB_TOKEN
+if (-not $Token) { $Token = $env:GITHUB_TOKEN }
+if (-not $Token) { $Token = $env:GH_TOKEN }
+$Headers = @{}
+$AssetHeaders = @{ Accept = 'application/octet-stream' }
+if ($Token) {
+    $Headers.Authorization = "Bearer $Token"
+    $AssetHeaders.Authorization = "Bearer $Token"
+}
 if (-not $Version) { $Version = $env:TEZGAH_VERSION }
 if (-not $Prefix) { $Prefix = $env:TEZGAH_PREFIX }
 if (-not $Prefix) { $Prefix = Join-Path $env:LOCALAPPDATA 'tezgah' }   # Windows' data dir
 $Prefix = Resolve-Full $Prefix
 if (-not $Version) {
     try {
-        $rel = Invoke-RestMethod "https://api.github.com/repos/$Repo/releases/latest"
+        $rel = Invoke-RestMethod "https://api.github.com/repos/$Repo/releases/latest" -Headers $Headers
         $Version = "$($rel.tag_name)".TrimStart('v')
     } catch {
-        throw "tezgah: cannot read the newest release of $Repo (no release yet, or no network): $_"
+        throw "tezgah: cannot read the newest release of $Repo (no release yet, or no network; a private repository needs TEZGAH_GITHUB_TOKEN, GITHUB_TOKEN or GH_TOKEN): $_"
     }
 }
 if (-not $Version -or $Version -match '[\\/]' -or $Version -in @('.', '..')) {
@@ -86,13 +104,28 @@ try {
     if ($env:TEZGAH_DIST) {
         $archive = Join-Path (Resolve-Full $env:TEZGAH_DIST) $name
         if (-not (Test-Path -LiteralPath $archive)) { throw "tezgah: no $archive" }
+    } elseif ($Token) {
+        $release = Invoke-RestMethod "https://api.github.com/repos/$Repo/releases/tags/v$Version" -Headers $Headers
+        $asset = $release.assets | Where-Object { $_.name -eq $name }
+        $sidecarAsset = $release.assets | Where-Object { $_.name -eq "$name.sha256" }
+        if (-not $asset -or -not $sidecarAsset) {
+            throw "tezgah: release v$Version of $Repo carries no $name"
+        }
+        try { [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 } catch { }
+        Invoke-WebRequest -UseBasicParsing -Headers $AssetHeaders `
+            "https://api.github.com/repos/$Repo/releases/assets/$($asset.id)" -OutFile $archive
     } else {
         $base = "https://github.com/$Repo/releases/download/v$Version"
         try { [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 } catch { }
         Invoke-WebRequest -UseBasicParsing "$base/$name" -OutFile $archive
     }
     $sidecar = "$archive.sha256"
-    if (-not $env:TEZGAH_DIST) {
+    if ($env:TEZGAH_DIST) {
+        # already beside the archive
+    } elseif ($Token) {
+        Invoke-WebRequest -UseBasicParsing -Headers $AssetHeaders `
+            "https://api.github.com/repos/$Repo/releases/assets/$($sidecarAsset.id)" -OutFile $sidecar
+    } else {
         Invoke-WebRequest -UseBasicParsing "$base/$name.sha256" -OutFile $sidecar
     }
 

package/packaging/install.sh

@@ -6,10 +6,14 @@
 # Runs packaging/upgrade.sh (the one place a version is fetched, verified,
 # unpacked and made current), then the installer from the tree it made current.
 # Needs sh and curl; tar and sha256sum are upgrade.sh's. Env, unlike its flags:
-# TEZGAH_REPO, TEZGAH_DIST, TEZGAH_PREFIX, as in upgrade.sh.
+# TEZGAH_REPO, TEZGAH_DIST, TEZGAH_PREFIX, as in upgrade.sh, and the token below
+# (a private TEZGAH_REPO serves no file without one).
 set -eu
 
 REPO=${TEZGAH_REPO:-r1z4x/tezgah}
+# raw.githubusercontent.com answers 404 to a session without a token when the
+# repository is private, and serves the same file to one that carries the bearer.
+token=${TEZGAH_GITHUB_TOKEN:-${GITHUB_TOKEN:-${GH_TOKEN:-}}}
 VERSION_ARG=
 PREFIX_ARG=
 REPLY_ARG=
@@ -37,8 +41,14 @@ else
     [ -z "$VERSION_ARG" ] || ref=v$VERSION_ARG
     work=$(mktemp -d "${TMPDIR:-/tmp}/tezgah-install.XXXXXX") || exit 1
     up=$work/upgrade.sh
-    curl -fsSL "https://raw.githubusercontent.com/$REPO/$ref/packaging/upgrade.sh" -o "$up" \
-        || { echo "tezgah: cannot fetch packaging/upgrade.sh at $ref" >&2; exit 1; }
+    url="https://raw.githubusercontent.com/$REPO/$ref/packaging/upgrade.sh"
+    if [ -n "$token" ]; then
+        printf 'Authorization: Bearer %s\n' "$token" | curl -fsSL -H @- "$url" -o "$up" \
+            || { echo "tezgah: cannot fetch packaging/upgrade.sh at $ref - if $REPO is private, set TEZGAH_GITHUB_TOKEN, GITHUB_TOKEN or GH_TOKEN" >&2; exit 1; }
+    else
+        curl -fsSL "$url" -o "$up" \
+            || { echo "tezgah: cannot fetch packaging/upgrade.sh at $ref - if $REPO is private, set TEZGAH_GITHUB_TOKEN, GITHUB_TOKEN or GH_TOKEN" >&2; exit 1; }
+    fi
 fi
 
 set -- --prefix "$PREFIX"                  # explicit flags: a prefix may hold a space

package/packaging/upgrade.sh

@@ -12,13 +12,15 @@
 # Callers: packaging/install.sh (a first install) and `tezgah-setup --upgrade`.
 # Neither re-implements the fetch, the checksum or the flip.
 #
-# Needs: sh, curl, tar, and sha256sum or shasum. No python. Uses `gh` when it
+# Needs: sh, curl, tar, awk, and sha256sum or shasum. No python. Uses `gh` when it
 # is on PATH to check the release's build provenance; without it, says so.
 # Env: TEZGAH_PREFIX, XDG_DATA_HOME, TEZGAH_VERSION, TEZGAH_REPO, TEZGAH_DIST
 #      (a directory holding tezgah-<V>.tar.gz + .sha256 - what build.sh --out
 #      writes; it swaps the release URL for that directory, one code path, and
 #      is how upgrade.sh is exercised without a published release), TEZGAH_GH
-#      (the gh to run for the provenance check; default `gh` on PATH).
+#      (the gh to run for the provenance check; default `gh` on PATH),
+#      TEZGAH_GITHUB_TOKEN / GITHUB_TOKEN / GH_TOKEN (the first one set is sent
+#      as the bearer a private $TEZGAH_REPO needs; with none, the public URLs).
 set -eu
 
 REPO=${TEZGAH_REPO:-r1z4x/tezgah}
@@ -39,10 +41,40 @@ die() {
     exit 1
 }
 
+# A private repository answers 404 to `releases/download/...` from a session without
+# a token (measured 2026-10-17, with the token as URL userinfo and as a header
+# alike), while the REST asset endpoint returns the blob for `Accept:
+# application/octet-stream` plus `Authorization: Bearer`. So the token decides which
+# URL is read, and a public repository - no token - keeps exactly the URL it had.
+token=${TEZGAH_GITHUB_TOKEN:-${GITHUB_TOKEN:-${GH_TOKEN:-}}}
+
+# Every read goes through here, so the bearer cannot be forgotten on one call. It
+# reaches curl on stdin (`-H @-`, curl 7.55+): an argument is in every user's `ps`.
+get() {   # get <url> [curl args...]
+    if [ -n "$token" ]; then
+        printf 'Authorization: Bearer %s\n' "$token" | curl -fsSL -H @- "$@"
+    else
+        curl -fsSL "$@"
+    fi
+}
+
+# The id of asset `$2` in the JSON of one release (`$1`). An asset's id is written
+# down in one place, its own `url` field, so the JSON is flattened, split at each
+# `"url":` - one fragment per asset, from its url to the next one - and the id read
+# from the fragment that names the file wanted. Empty, not an error, when the
+# release carries no such asset; the caller says so.
+asset_id() {
+    printf '%s\n' "$1" | tr -d '[:space:]' | awk -v want="\"name\":\"$2\"" '
+        { n = split($0, o, "\"url\":")
+          for (i = 1; i <= n; i++)
+              if (index(o[i], want) && match(o[i], /"id":[0-9]+/))
+                  { print substr(o[i], RSTART + 5, RLENGTH - 5); exit } }'
+}
+
 # The newest release tag. The API answers `tag_name`; the raw redirect would
 # too, but GitHub answers this without a rate-limit surprise on a repeat run.
 latest_release() {
-    body=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" 2>/dev/null) \
+    body=$(get "https://api.github.com/repos/$REPO/releases/latest" 2>/dev/null) \
         || return 1
     tag=$(printf '%s\n' "$body" \
         | sed -n 's/.*"tag_name":[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)
@@ -77,18 +109,40 @@ if [ -n "${TEZGAH_DIST:-}" ]; then
         *)  dist=$PWD/$TEZGAH_DIST ;;
     esac
     base="file://$dist"
+    assets=
+elif [ -n "$token" ]; then
+    # The asset endpoint is addressed by id, and the release JSON is the only
+    # place that id is written down.
+    rel=$(get "https://api.github.com/repos/$REPO/releases/tags/v$VERSION") \
+        || die "cannot read release v$VERSION of $REPO with the token in TEZGAH_GITHUB_TOKEN/GITHUB_TOKEN/GH_TOKEN"
+    id=$(asset_id "$rel" "tezgah-$VERSION.tar.gz")
+    id_sidecar=$(asset_id "$rel" "tezgah-$VERSION.tar.gz.sha256")
+    [ -n "$id" ] && [ -n "$id_sidecar" ] \
+        || die "release v$VERSION of $REPO carries no tezgah-$VERSION.tar.gz"
+    base="https://api.github.com/repos/$REPO/releases/assets"
+    assets=$base
 else
     base="https://github.com/$REPO/releases/download/v$VERSION"
+    assets=
 fi
 
 work=$(mktemp -d "${TMPDIR:-/tmp}/tezgah-upgrade.XXXXXX") || die "cannot create a temp dir"
 trap 'rm -rf "$work"' EXIT INT TERM
 
 name=tezgah-$VERSION.tar.gz
-curl -fsSL "$base/$name" -o "$work/$name" \
-    || die "cannot fetch $name from $base"
-curl -fsSL "$base/$name.sha256" -o "$work/$name.sha256" \
-    || die "cannot fetch $name.sha256 from $base"
+if [ -n "$assets" ]; then
+    # Both files come from the same release, and neither blob is served without
+    # this Accept: the endpoint answers JSON metadata otherwise.
+    get -H "Accept: application/octet-stream" "$assets/$id" -o "$work/$name" \
+        || die "cannot fetch $name from $assets/$id"
+    get -H "Accept: application/octet-stream" "$assets/$id_sidecar" -o "$work/$name.sha256" \
+        || die "cannot fetch $name.sha256 from $assets/$id_sidecar"
+else
+    get "$base/$name" -o "$work/$name" \
+        || die "cannot fetch $name from $base - if $REPO is private, set TEZGAH_GITHUB_TOKEN, GITHUB_TOKEN or GH_TOKEN"
+    get "$base/$name.sha256" -o "$work/$name.sha256" \
+        || die "cannot fetch $name.sha256 from $base - if $REPO is private, set TEZGAH_GITHUB_TOKEN, GITHUB_TOKEN or GH_TOKEN"
+fi
 
 want=$(sed -n '1s/[[:space:]].*//p' "$work/$name.sha256")
 got=$(sha256_of "$work/$name")

package/skills/ai-research/SKILL.md

@@ -1,17 +1,22 @@
 ---
 name: ai-research
 description: >
-  The vendored AI-research-SKILLs library - 98 upstream skills in 23 categories,
-  MIT - that now ships with tezgah. Use when a research line needs AI or ML
-  machinery: training or fine-tuning a model, serving or quantizing one,
-  evaluating a benchmark, reading model internals, building a retrieval or agent
-  pipeline, tracking runs, or writing the result up. Read the one entry the work
-  needs, never the tree. Do NOT use for code discovery ("where is X", "who calls
-  Y") - that is the code graph.
+  Use when a research line needs AI/ML machinery: training, fine-tuning,
+  serving, evals; ince ayar, dil modeli. Not for RL environments - use `rl-env`.
 ---
 
 # ai-research
 
+## When to use
+
+The vendored AI-research-SKILLs library - 98 upstream skills in 23 categories,
+MIT - that now ships with tezgah. Use when a research line needs AI or ML
+machinery: training or fine-tuning a model, serving or quantizing one,
+evaluating a benchmark, reading model internals, building a retrieval or agent
+pipeline, tracking runs, or writing the result up. Read the one entry the work
+needs, never the tree. Do NOT use for code discovery ("where is X", "who calls
+Y") - that is the code graph.
+
 Ninety-eight skills from Orchestra Research's `AI-research-SKILLs`, vendored into
 this repository at revision `773a529` (2026-06-15, MIT) and kept in the upstream
 layout, so a path here is the path there. Re-vendor, or verify the tree, with
@@ -27,8 +32,10 @@ before.
 
 1. **`index/<stage>.md`** - six files, one per stage of a research line. Read the
    one that matches the work in hand; it lists every entry with its purpose.
-2. **the entry's `SKILL.md`** - the file the index line names, e.g.
-   `11-evaluation/lm-evaluation-harness/SKILL.md`. That is the upstream body.
+2. **the entry's `ENTRY.md`** - the file the index line names, e.g.
+   `11-evaluation/lm-evaluation-harness/ENTRY.md`. That is the upstream body:
+   upstream's `SKILL.md`, renamed so a host that lists every `SKILL.md` below its
+   skills directory does not list it. A body that says `SKILL.md` means this file.
 3. **its `references/`** - the detail the body points at, when the body is not
    enough.
 
@@ -57,7 +64,7 @@ Each index line can carry a flag, and they are not decoration:
   live links in the same entry still work.
 
 An entry with no body vendored would be a line without a file - there is none:
-every one of the 98 ships its `SKILL.md`.
+every one of the 98 ships its `ENTRY.md`.
 
 ## Where tezgah's own rules still win
 
@@ -75,14 +82,14 @@ account, a paid service or the user's data still needs the user's yes first.
   this contract's protocol-before-run rule.
 - `20-ml-paper-writing/ml-paper-writing/references/citation-workflow.md` - how to
   verify a reference instead of writing one from memory.
-- `20-ml-paper-writing/academic-plotting/SKILL.md` - chart-type rules, a
+- `20-ml-paper-writing/academic-plotting/ENTRY.md` - chart-type rules, a
   colourblind-safe palette and venue column widths; every line ends in a figure.
-- `22-agent-native-research-artifact/rigor-reviewer/SKILL.md` - the 1-5 scoring
+- `22-agent-native-research-artifact/rigor-reviewer/ENTRY.md` - the 1-5 scoring
   anchors and severity inventory behind this contract's six-dimension review.
-- `22-agent-native-research-artifact/compiler/SKILL.md` - evidence fidelity: exact
+- `22-agent-native-research-artifact/compiler/ENTRY.md` - evidence fidelity: exact
   numbers, a derived subset never named `Table N`, every evidence file carrying
   its source.
-- `11-evaluation/lm-evaluation-harness/SKILL.md` - the runnable benchmark recipe a
+- `11-evaluation/lm-evaluation-harness/ENTRY.md` - the runnable benchmark recipe a
   research line usually quotes.
 
 ## Provenance

package/skills/ai-research/SOURCE

@@ -10,12 +10,14 @@ contributing author of that entry. Checkout for a re-vendor:
 
 Every skill's `SKILL.md` and every markdown file beside it, in the upstream
 layout, because a vendored path is its provenance. 98 skills across 23
-categories, 365 files, 4202519 bytes.
+categories, 365 files, 4202519 bytes. One rename: each entry's `SKILL.md` sits at
+the upstream path as `ENTRY.md`, bytes unchanged, so a host that lists every
+`SKILL.md` below its skills directory (codex, Cursor) does not list it.
 
 ## What is not, and why
 
 Files: `03-fine-tuning/unsloth/references/llms-full.md`, `03-fine-tuning/unsloth/references/llms-txt.md`, `08-distributed-training/deepspeed/references/tutorials.md` - machine-scraped reference dumps, which the entry's own
-`SKILL.md` already distils.
+`ENTRY.md` already distils.
 
 Directories: `20-ml-paper-writing/ml-paper-writing/templates`, `20-ml-paper-writing/systems-paper-writing/templates` - LaTeX class/bst/bib trees and example PDFs,
 re-downloadable from each venue.
@@ -27,9 +29,9 @@ is dropped by the importer's `*.md` filter, and `demos/`, `docs/`,
 ## The only modification
 
 A markdown file that carries no YAML frontmatter gets one attribution
-comment on its first line. `SKILL.md` files are byte-for-byte upstream,
-frontmatter included. `skills/ai-research/SKILL.md` is tezgah's own and is
-not part of the manifest.
+comment on its first line. `ENTRY.md` files are byte-for-byte upstream
+`SKILL.md`, frontmatter included. `skills/ai-research/SKILL.md` is
+tezgah's own and is not part of the manifest.
 
 ## Re-vendoring
 

package/skills/ai-research/index/1-frame.md

@@ -10,9 +10,9 @@ links N reference files upstream does not ship.
 
 | entry | file | what it covers | flags |
 |---|---|---|---|
-| `0-autoresearch-skill` | `0-autoresearch-skill/SKILL.md` | Orchestrates end-to-end autonomous AI research projects using a two-loop architecture. |  |
-| `brainstorming-research-ideas` | `21-research-ideation/brainstorming-research-ideas/SKILL.md` | Guides researchers through structured ideation frameworks to discover high-impact research directions. |  |
-| `creative-thinking-for-research` | `21-research-ideation/creative-thinking-for-research/SKILL.md` | Applies cognitive science frameworks for creative thinking to CS and AI research ideation. |  |
-| `compiler` | `22-agent-native-research-artifact/compiler/SKILL.md` | Compiles any research input — PDF papers, GitHub repositories, experiment logs, code directories, or raw notes — into a complete Agent-Native Research Artifact (ARA) with ... |  |
-| `research-manager` | `22-agent-native-research-artifact/research-manager/SKILL.md` | Records research provenance as a post-task epilogue, scanning conversation history at the end of a coding or research session to extract decisions, experiments, dead ends, claims ... |  |
-| `rigor-reviewer` | `22-agent-native-research-artifact/rigor-reviewer/SKILL.md` | Performs ARA Seal Level 2 semantic epistemic review on Agent-Native Research Artifacts, scoring six dimensions (evidence relevance, falsifiability, scope calibration, argument ... |  |
+| `0-autoresearch-skill` | `0-autoresearch-skill/ENTRY.md` | Orchestrates end-to-end autonomous AI research projects using a two-loop architecture. |  |
+| `brainstorming-research-ideas` | `21-research-ideation/brainstorming-research-ideas/ENTRY.md` | Guides researchers through structured ideation frameworks to discover high-impact research directions. |  |
+| `creative-thinking-for-research` | `21-research-ideation/creative-thinking-for-research/ENTRY.md` | Applies cognitive science frameworks for creative thinking to CS and AI research ideation. |  |
+| `compiler` | `22-agent-native-research-artifact/compiler/ENTRY.md` | Compiles any research input — PDF papers, GitHub repositories, experiment logs, code directories, or raw notes — into a complete Agent-Native Research Artifact (ARA) with ... |  |
+| `research-manager` | `22-agent-native-research-artifact/research-manager/ENTRY.md` | Records research provenance as a post-task epilogue, scanning conversation history at the end of a coding or research session to extract decisions, experiments, dead ends, claims ... |  |
+| `rigor-reviewer` | `22-agent-native-research-artifact/rigor-reviewer/ENTRY.md` | Performs ARA Seal Level 2 semantic epistemic review on Agent-Native Research Artifacts, scoring six dimensions (evidence relevance, falsifiability, scope calibration, argument ... |  |

package/skills/ai-research/index/2-data.md

@@ -10,12 +10,12 @@ links N reference files upstream does not ship.
 
 | entry | file | what it covers | flags |
 |---|---|---|---|
-| `huggingface-tokenizers` | `02-tokenization/huggingface-tokenizers/SKILL.md` | Fast tokenizers optimized for research and production. |  |
-| `sentencepiece` | `02-tokenization/sentencepiece/SKILL.md` | Language-independent tokenizer treating text as raw Unicode. |  |
-| `nemo-curator` | `05-data-processing/nemo-curator/SKILL.md` | GPU-accelerated data curation for LLM training. |  |
-| `ray-data` | `05-data-processing/ray-data/SKILL.md` | Scalable data processing for ML workloads. |  |
-| `chroma` | `15-rag/chroma/SKILL.md` | Open-source embedding database for AI applications. |  |
-| `faiss` | `15-rag/faiss/SKILL.md` | Facebook's library for efficient similarity search and clustering of dense vectors. |  |
-| `pinecone` | `15-rag/pinecone/SKILL.md` | Managed vector database for production AI applications. |  |
-| `qdrant` | `15-rag/qdrant/SKILL.md` | High-performance vector similarity search engine for RAG and semantic search. |  |
-| `sentence-transformers` | `15-rag/sentence-transformers/SKILL.md` | Framework for state-of-the-art sentence, text, and image embeddings. |  |
+| `huggingface-tokenizers` | `02-tokenization/huggingface-tokenizers/ENTRY.md` | Fast tokenizers optimized for research and production. |  |
+| `sentencepiece` | `02-tokenization/sentencepiece/ENTRY.md` | Language-independent tokenizer treating text as raw Unicode. |  |
+| `nemo-curator` | `05-data-processing/nemo-curator/ENTRY.md` | GPU-accelerated data curation for LLM training. |  |
+| `ray-data` | `05-data-processing/ray-data/ENTRY.md` | Scalable data processing for ML workloads. |  |
+| `chroma` | `15-rag/chroma/ENTRY.md` | Open-source embedding database for AI applications. |  |
+| `faiss` | `15-rag/faiss/ENTRY.md` | Facebook's library for efficient similarity search and clustering of dense vectors. |  |
+| `pinecone` | `15-rag/pinecone/ENTRY.md` | Managed vector database for production AI applications. |  |
+| `qdrant` | `15-rag/qdrant/ENTRY.md` | High-performance vector similarity search engine for RAG and semantic search. |  |
+| `sentence-transformers` | `15-rag/sentence-transformers/ENTRY.md` | Framework for state-of-the-art sentence, text, and image embeddings. |  |

package/skills/ai-research/index/3-train.md

@@ -10,39 +10,39 @@ links N reference files upstream does not ship.
 
 | entry | file | what it covers | flags |
 |---|---|---|---|
-| `litgpt` | `01-model-architecture/litgpt/SKILL.md` | Implements and trains LLMs using Lightning AI's LitGPT with 20+ pretrained architectures (Llama, Gemma, Phi, Qwen, Mistral). |  |
-| `mamba` | `01-model-architecture/mamba/SKILL.md` | State-space model with O(n) complexity vs Transformers' O(n²). | dead-links: 2 |
-| `nanogpt` | `01-model-architecture/nanogpt/SKILL.md` | Educational GPT implementation in ~300 lines. |  |
-| `rwkv` | `01-model-architecture/rwkv/SKILL.md` | RNN+Transformer hybrid with O(n) inference. | stale-api |
-| `torchtitan` | `01-model-architecture/torchtitan/SKILL.md` | Provides PyTorch-native distributed LLM pretraining using torchtitan with 4D parallelism (FSDP2, TP, PP, CP). |  |
-| `axolotl` | `03-fine-tuning/axolotl/SKILL.md` | Expert guidance for fine-tuning LLMs with Axolotl - YAML configs, 100+ models, LoRA/QLoRA, DPO/KTO/ORPO/GRPO, multimodal support | generated |
-| `llama-factory` | `03-fine-tuning/llama-factory/SKILL.md` | Expert guidance for fine-tuning LLMs with LLaMA-Factory - WebUI no-code, 100+ models, 2/3/4/5/6/8-bit QLoRA, multimodal support | generated |
-| `peft` | `03-fine-tuning/peft/SKILL.md` | Parameter-efficient fine-tuning for LLMs using LoRA, QLoRA, and 25+ methods. |  |
-| `unsloth` | `03-fine-tuning/unsloth/SKILL.md` | Expert guidance for fast fine-tuning with Unsloth - 2-5x faster training, 50-80% less memory, LoRA/QLoRA optimization | generated |
-| `grpo-rl-training` | `06-post-training/grpo-rl-training/SKILL.md` | Expert guidance for GRPO/RL fine-tuning with TRL for reasoning and task-specific model training |  |
-| `miles` | `06-post-training/miles/SKILL.md` | Provides guidance for enterprise-grade RL training using miles, a production-ready fork of slime. |  |
-| `openrlhf` | `06-post-training/openrlhf/SKILL.md` | High-performance RLHF framework with Ray+vLLM acceleration. |  |
-| `simpo` | `06-post-training/simpo/SKILL.md` | Simple Preference Optimization for LLM alignment. |  |
-| `slime` | `06-post-training/slime/SKILL.md` | Provides guidance for LLM post-training with RL using slime, a Megatron+SGLang framework. |  |
-| `torchforge` | `06-post-training/torchforge/SKILL.md` | Provides guidance for PyTorch-native agentic RL using torchforge, Meta's library separating infra from algorithms. |  |
-| `trl-fine-tuning` | `06-post-training/trl-fine-tuning/SKILL.md` | Fine-tune LLMs using reinforcement learning with TRL - SFT for instruction tuning, DPO for preference alignment, PPO/GRPO for reward optimization, and reward model training. |  |
-| `verl` | `06-post-training/verl/SKILL.md` | Provides guidance for training LLMs with reinforcement learning using verl (Volcano Engine RL). | dead-links: 1 |
-| `accelerate` | `08-distributed-training/accelerate/SKILL.md` | Simplest distributed training API. |  |
-| `deepspeed` | `08-distributed-training/deepspeed/SKILL.md` | Expert guidance for distributed training with DeepSpeed - ZeRO optimization stages, pipeline parallelism, FP16/BF16/FP8, 1-bit Adam, sparse attention | generated |
-| `megatron-core` | `08-distributed-training/megatron-core/SKILL.md` | Trains large language models (2B-462B parameters) using NVIDIA Megatron-Core with advanced parallelism strategies. |  |
-| `pytorch-fsdp2` | `08-distributed-training/pytorch-fsdp2/SKILL.md` | Adds PyTorch FSDP2 (fully_shard) to training scripts with correct init, sharding, mixed precision/offload config, and distributed checkpointing. |  |
-| `pytorch-lightning` | `08-distributed-training/pytorch-lightning/SKILL.md` | High-level PyTorch framework with Trainer class, automatic distributed training (DDP/FSDP/DeepSpeed), callbacks system, and minimal boilerplate. |  |
-| `ray-train` | `08-distributed-training/ray-train/SKILL.md` | Distributed training orchestration across clusters. | dead-links: 1 |
-| `awq` | `10-optimization/awq/SKILL.md` | Activation-aware weight quantization for 4-bit LLM compression with 3x speedup and minimal accuracy loss. | stale-api |
-| `bitsandbytes` | `10-optimization/bitsandbytes/SKILL.md` | Quantizes LLMs to 8-bit or 4-bit for 50-75% memory reduction with minimal accuracy loss. |  |
-| `flash-attention` | `10-optimization/flash-attention/SKILL.md` | Optimizes transformer attention with Flash Attention for 2-4x speedup and 10-20x memory reduction. | dead-links: 2 |
-| `gguf` | `10-optimization/gguf/SKILL.md` | GGUF format and llama.cpp quantization for efficient CPU/GPU inference. |  |
-| `gptq` | `10-optimization/gptq/SKILL.md` | Post-training 4-bit quantization for LLMs with minimal accuracy loss. |  |
-| `hqq` | `10-optimization/hqq/SKILL.md` | Half-Quadratic Quantization for LLMs without calibration data. |  |
-| `ml-training-recipes` | `10-optimization/ml-training-recipes/SKILL.md` | Battle-tested PyTorch training recipes for all domains — LLMs, vision, diffusion, medical imaging, protein/drug discovery, spatial omics, genomics. |  |
-| `knowledge-distillation` | `19-emerging-techniques/knowledge-distillation/SKILL.md` | Compress large language models using knowledge distillation from teacher to student models. |  |
-| `long-context` | `19-emerging-techniques/long-context/SKILL.md` | Extend context windows of transformer models using RoPE, YaRN, ALiBi, and position interpolation techniques. |  |
-| `model-merging` | `19-emerging-techniques/model-merging/SKILL.md` | Merge multiple fine-tuned models using mergekit to combine capabilities without retraining. |  |
-| `model-pruning` | `19-emerging-techniques/model-pruning/SKILL.md` | Reduce LLM size and accelerate inference using pruning techniques like Wanda and SparseGPT. |  |
-| `moe-training` | `19-emerging-techniques/moe-training/SKILL.md` | Train Mixture of Experts (MoE) models using DeepSpeed or HuggingFace. |  |
-| `speculative-decoding` | `19-emerging-techniques/speculative-decoding/SKILL.md` | Accelerate LLM inference using speculative decoding, Medusa multiple heads, and lookahead decoding techniques. | dead-links: 1 |
+| `litgpt` | `01-model-architecture/litgpt/ENTRY.md` | Implements and trains LLMs using Lightning AI's LitGPT with 20+ pretrained architectures (Llama, Gemma, Phi, Qwen, Mistral). |  |
+| `mamba` | `01-model-architecture/mamba/ENTRY.md` | State-space model with O(n) complexity vs Transformers' O(n²). | dead-links: 2 |
+| `nanogpt` | `01-model-architecture/nanogpt/ENTRY.md` | Educational GPT implementation in ~300 lines. |  |
+| `rwkv` | `01-model-architecture/rwkv/ENTRY.md` | RNN+Transformer hybrid with O(n) inference. | stale-api |
+| `torchtitan` | `01-model-architecture/torchtitan/ENTRY.md` | Provides PyTorch-native distributed LLM pretraining using torchtitan with 4D parallelism (FSDP2, TP, PP, CP). |  |
+| `axolotl` | `03-fine-tuning/axolotl/ENTRY.md` | Expert guidance for fine-tuning LLMs with Axolotl - YAML configs, 100+ models, LoRA/QLoRA, DPO/KTO/ORPO/GRPO, multimodal support | generated |
+| `llama-factory` | `03-fine-tuning/llama-factory/ENTRY.md` | Expert guidance for fine-tuning LLMs with LLaMA-Factory - WebUI no-code, 100+ models, 2/3/4/5/6/8-bit QLoRA, multimodal support | generated |
+| `peft` | `03-fine-tuning/peft/ENTRY.md` | Parameter-efficient fine-tuning for LLMs using LoRA, QLoRA, and 25+ methods. |  |
+| `unsloth` | `03-fine-tuning/unsloth/ENTRY.md` | Expert guidance for fast fine-tuning with Unsloth - 2-5x faster training, 50-80% less memory, LoRA/QLoRA optimization | generated |
+| `grpo-rl-training` | `06-post-training/grpo-rl-training/ENTRY.md` | Expert guidance for GRPO/RL fine-tuning with TRL for reasoning and task-specific model training |  |
+| `miles` | `06-post-training/miles/ENTRY.md` | Provides guidance for enterprise-grade RL training using miles, a production-ready fork of slime. |  |
+| `openrlhf` | `06-post-training/openrlhf/ENTRY.md` | High-performance RLHF framework with Ray+vLLM acceleration. |  |
+| `simpo` | `06-post-training/simpo/ENTRY.md` | Simple Preference Optimization for LLM alignment. |  |
+| `slime` | `06-post-training/slime/ENTRY.md` | Provides guidance for LLM post-training with RL using slime, a Megatron+SGLang framework. |  |
+| `torchforge` | `06-post-training/torchforge/ENTRY.md` | Provides guidance for PyTorch-native agentic RL using torchforge, Meta's library separating infra from algorithms. |  |
+| `trl-fine-tuning` | `06-post-training/trl-fine-tuning/ENTRY.md` | Fine-tune LLMs using reinforcement learning with TRL - SFT for instruction tuning, DPO for preference alignment, PPO/GRPO for reward optimization, and reward model training. |  |
+| `verl` | `06-post-training/verl/ENTRY.md` | Provides guidance for training LLMs with reinforcement learning using verl (Volcano Engine RL). | dead-links: 1 |
+| `accelerate` | `08-distributed-training/accelerate/ENTRY.md` | Simplest distributed training API. |  |
+| `deepspeed` | `08-distributed-training/deepspeed/ENTRY.md` | Expert guidance for distributed training with DeepSpeed - ZeRO optimization stages, pipeline parallelism, FP16/BF16/FP8, 1-bit Adam, sparse attention | generated |
+| `megatron-core` | `08-distributed-training/megatron-core/ENTRY.md` | Trains large language models (2B-462B parameters) using NVIDIA Megatron-Core with advanced parallelism strategies. |  |
+| `pytorch-fsdp2` | `08-distributed-training/pytorch-fsdp2/ENTRY.md` | Adds PyTorch FSDP2 (fully_shard) to training scripts with correct init, sharding, mixed precision/offload config, and distributed checkpointing. |  |
+| `pytorch-lightning` | `08-distributed-training/pytorch-lightning/ENTRY.md` | High-level PyTorch framework with Trainer class, automatic distributed training (DDP/FSDP/DeepSpeed), callbacks system, and minimal boilerplate. |  |
+| `ray-train` | `08-distributed-training/ray-train/ENTRY.md` | Distributed training orchestration across clusters. | dead-links: 1 |
+| `awq` | `10-optimization/awq/ENTRY.md` | Activation-aware weight quantization for 4-bit LLM compression with 3x speedup and minimal accuracy loss. | stale-api |
+| `bitsandbytes` | `10-optimization/bitsandbytes/ENTRY.md` | Quantizes LLMs to 8-bit or 4-bit for 50-75% memory reduction with minimal accuracy loss. |  |
+| `flash-attention` | `10-optimization/flash-attention/ENTRY.md` | Optimizes transformer attention with Flash Attention for 2-4x speedup and 10-20x memory reduction. | dead-links: 2 |
+| `gguf` | `10-optimization/gguf/ENTRY.md` | GGUF format and llama.cpp quantization for efficient CPU/GPU inference. |  |
+| `gptq` | `10-optimization/gptq/ENTRY.md` | Post-training 4-bit quantization for LLMs with minimal accuracy loss. |  |
+| `hqq` | `10-optimization/hqq/ENTRY.md` | Half-Quadratic Quantization for LLMs without calibration data. |  |
+| `ml-training-recipes` | `10-optimization/ml-training-recipes/ENTRY.md` | Battle-tested PyTorch training recipes for all domains — LLMs, vision, diffusion, medical imaging, protein/drug discovery, spatial omics, genomics. |  |
+| `knowledge-distillation` | `19-emerging-techniques/knowledge-distillation/ENTRY.md` | Compress large language models using knowledge distillation from teacher to student models. |  |
+| `long-context` | `19-emerging-techniques/long-context/ENTRY.md` | Extend context windows of transformer models using RoPE, YaRN, ALiBi, and position interpolation techniques. |  |
+| `model-merging` | `19-emerging-techniques/model-merging/ENTRY.md` | Merge multiple fine-tuned models using mergekit to combine capabilities without retraining. |  |
+| `model-pruning` | `19-emerging-techniques/model-pruning/ENTRY.md` | Reduce LLM size and accelerate inference using pruning techniques like Wanda and SparseGPT. |  |
+| `moe-training` | `19-emerging-techniques/moe-training/ENTRY.md` | Train Mixture of Experts (MoE) models using DeepSpeed or HuggingFace. |  |
+| `speculative-decoding` | `19-emerging-techniques/speculative-decoding/ENTRY.md` | Accelerate LLM inference using speculative decoding, Medusa multiple heads, and lookahead decoding techniques. | dead-links: 1 |