@r1z4x/tezgah 1.9.2 → 1.13.0

package/skills/product-flow/SKILL.md

@@ -1,18 +1,23 @@
 ---
 name: product-flow
 description: >
-  Carries a new product capability from evidence to a measured result: it walks
-  the nine steps of the flow in order - research, metrics, assumptions,
-  decision, instrumentation, forward spec, design, build, re-measure - and does
-  the first step whose artifact is missing with the skill that step names, so
-  each hand-off is a written artifact that names the one before it instead of a
-  memory. Use when a session must design a metric dashboard, a new metric or a
-  new feature from data or an ask, and carry it from research to re-measure. Not
-  for auditing an existing feature - use `feature-audit`.
+  Use when a new metric dashboard or feature is carried from data to re-measure;
+  yeni özellik, metrik, ölç. Not for an existing feature - use `feature-audit`.
 ---
 
 # product-flow
 
+## When to use
+
+Carries a new product capability from evidence to a measured result: it walks
+the nine steps of the flow in order - research, metrics, assumptions, decision,
+instrumentation, forward spec, design, build, re-measure - and does the first
+step whose artifact is missing with the skill that step names, so each hand-off
+is a written artifact that names the one before it instead of a memory. Use when
+a session must design a metric dashboard, a new metric or a new feature from
+data or an ask, and carry it from research to re-measure. Not for auditing an
+existing feature - use `feature-audit`.
+
 A new product capability - a dashboard over a data file, a metric, a feature
 someone asked for - drifts when its steps live in the session's head: the chart
 gets drawn before anyone says which goal it serves, and nobody comes back to see
@@ -57,7 +62,7 @@ spec in `spec.md`. Each step's artifact names the earlier artifact it rests on.
 7. **design** (`design-contract`). A component in `.tezgah/design-contract.md`
    that names the decision it serves.
 8. **build** (`design-contract`). Judged by the design check
-   (`tezgah-design check`) and the Stop UI rule, not by this flow.
+   (`~/.config/tezgah/bin/tezgah-design check`) and the Stop UI rule, not by this flow.
 9. **re-measure** (`analyze-app`). Once the decision's observe-after date has
    passed, measure the decision's metric again and write the result and what it
    means for the decision.

package/skills/research/SKILL.md

@@ -1,22 +1,28 @@
 ---
 name: research
 description: >
-  Runs an auditable research line in the repository: the two-loop rhythm
-  (bootstrap, inner experiment loop, outer synthesis), the workspace that holds
-  its state, protocol-before-run so a prediction is provably older than its
-  results, a six-dimension review of the claims before they are reported, and a
-  provenance record of what the session decided. Use when a task's deliverable is
-  evidence rather than a code change: a literature or reference review, a
-  hypothesis to test, a comparison of variants, a benchmark or ablation, a
-  research report or figure, or when the user says "research", "investigate",
-  "araştır", "literatür", "hipotez", "deney", "ablation", "benchmark". Route the
-  execution through the OpenResearch CLI when it is installed. Do NOT use for
-  code discovery ("where is X", "who calls Y") - that is the code graph. Not for
-  a product question - use `product-analysis`.
+  Use when the deliverable is evidence: a literature or reference review;
+  literatür, araştır, hipotez, deney, kaynak. Not for products - use
+  `product-analysis`.
 ---
 
 # research
 
+## When to use
+
+Runs an auditable research line in the repository: the two-loop rhythm
+(bootstrap, inner experiment loop, outer synthesis), the workspace that holds
+its state, protocol-before-run so a prediction is provably older than its
+results, a six-dimension review of the claims before they are reported, and a
+provenance record of what the session decided. Use when a task's deliverable is
+evidence rather than a code change: a literature or reference review, a
+hypothesis to test, a comparison of variants, a benchmark or ablation, a
+research report or figure, or when the user says "research", "investigate",
+"araştır", "literatür", "hipotez", "deney", "ablation", "benchmark". Route the
+execution through the OpenResearch CLI when it is installed. Do NOT use for code
+discovery ("where is X", "who calls Y") - that is the code graph. Not for a
+product question - use `product-analysis`.
+
 A research task's deliverable is evidence. Everything here exists so that the
 evidence survives the session that produced it: the state on disk, the protocol
 committed before the run, the claims with their falsification criteria, and the
@@ -67,8 +73,8 @@ breaking one silently invalidates the run:
 - grow the experiment tree downward, not sideways.
 
 Load its manual before driving it: `orx skill`, then the module for the step
-(`orx skill lit-review` for sources; `orx skill experiment-tree` and
-`orx skill evidence` for a measured line).
+(`orx skill lit-review` for sources; `orx skill experiment-tree`,
+`orx skill orx-results` and `orx skill orx-logs` for a measured line).
 Local runs need no login; managed compute does - run locally at a scale that fits,
 and ask for `orx login` only when the question cannot be answered without it.
 If `orx` is absent, say the research tooling is unavailable and do not improvise
@@ -86,8 +92,8 @@ One directory per research line, `<repo>/.tezgah/research/<slug>/`:
 | `state.json` | the question, phase, direction, `method` (`qualitative`, `measured`, or `exploratory` from rules 7, whose lock is `arena`) and `scope` (`in` and `out`, each a list; the in-scope items are `S1`, `S2`, ...), the locked evaluation of a measured line (`metric`, `baseline`, `locked_at`, optional `environment`, and the optional two-gate pair `capability_tolerance` + `counter_metric`), the hypothesis list, `rules` (the rule set the line was opened under), `deliverable` (`kind`: design, plan, analysis, code or finding; `path`; `ask`, the ask's items one per entry; `min_variants`), and `supersedes` when it is a new version of an older line |
 | `log.md` | the decision timeline: one line per decision, experiment, dead end or pivot, with the evidence that drove it |
 | `findings.md` | `## What we know`, `## Patterns`, `## Lessons`, `## Open questions` |
-| `claims.jsonl` | one claim per line: `statement`, `status`, `provenance`, `kind`, `falsification`, `proof`, `dependencies`, `trace` (the in-scope item it answers, `S<n>`, required from rules 5), `scope` (what the claim's numbers were measured on, and it may not be wider than the rows it rests on), and `supersedes` when the claim replaces an earlier one - recorded with `tezgah-research claim <slug>`, never by editing the file |
-| `ideas.jsonl`, `stages.jsonl`, `tournament.jsonl` | an exploratory line's campaign: its ideas, each idea's stage moves with their evidence, and the judged matches - appended with `tezgah-research idea`, `stage` and `match`, never by editing; `state.json` `arena` is its lock (see "Exploratory lines") |
+| `claims.jsonl` | one claim per line: `statement`, `status`, `provenance`, `kind`, `falsification`, `proof`, `dependencies`, `trace` (the in-scope item it answers, `S<n>`, required from rules 5), `scope` (what the claim's numbers were measured on, and it may not be wider than the rows it rests on), and `supersedes` when the claim replaces an earlier one - recorded with `~/.config/tezgah/bin/tezgah-research claim <slug>`, never by editing the file |
+| `ideas.jsonl`, `stages.jsonl`, `tournament.jsonl` | an exploratory line's campaign: its ideas, each idea's stage moves with their evidence, and the judged matches - appended with `~/.config/tezgah/bin/tezgah-research idea`, `stage` and `match`, never by editing; `state.json` `arena` is its lock (see "Exploratory lines") |
 | `experiments/<hypothesis>/` | `protocol.md`, `results.jsonl` (one JSON object per row, each carrying its `source`, its `scope` - what the numbers were measured on - and, when that scope is `fixture`, the `fixture` description of the input that was generated), `analysis.md`, and `raw/<runId>.log` for a run read back from the engine |
 | `literature/` | one file per source, saved when you read it, not later, and each named by its row in `literature/INDEX.jsonl` - every file under it, at any depth and of any extension, is a source the index names |
 | `decisions/<id>/` | one comparison of the deliverable's variants: `criteria.json`, `variants.jsonl`, `comparison.jsonl` and `decision.md` - see "Variants" below |
@@ -116,12 +122,13 @@ Scaffold and check it with the CLI (`~/.config/tezgah/bin/tezgah-research`, or
 
 ```sh
 ~/.config/tezgah/bin/tezgah-research init my-line --ask "<the user's words>" --question "does X hold under Y?" \
-    --method measured --in "X under Y" --out "X under Z"
+    --method measured --class R6 --in "X under Y" --out "X under Z"
 ~/.config/tezgah/bin/tezgah-research commit my-line "<message>"   # commit in .tezgah's repo
 ~/.config/tezgah/bin/tezgah-research check    # open lines + done/ seals; 0 clean, 1 broken rule, 2 misuse
 ~/.config/tezgah/bin/tezgah-research check --all-lines   # every line in full, done/ included
 ~/.config/tezgah/bin/tezgah-research check --strict   # the unprovable becomes a refusal
-~/.config/tezgah/bin/tezgah-research check --orx      # the run command registered here
+~/.config/tezgah/bin/tezgah-research check --orx      # the run command registered here, and the run census
+~/.config/tezgah/bin/tezgah-research check --online   # re-fetch the citation receipts (rules 8)
 ~/.config/tezgah/bin/tezgah-research status
 ~/.config/tezgah/bin/tezgah-research claim my-line   # one JSON object on stdin
 ~/.config/tezgah/bin/tezgah-research migrate my-line [--dry-run]
@@ -129,6 +136,26 @@ Scaffold and check it with the CLI (`~/.config/tezgah/bin/tezgah-research`, or
 ~/.config/tezgah/bin/tezgah-research import <other-checkout> my-line   # move a line with its history
 ```
 
+`--class R1..R12` routes the line by question type (rules 8): `init` prints the
+obligations - the step names `check` caps a claim's certainty with when one is
+missing - the tier's budget, and every done line's claim that overlaps the question.
+An R0 question (a fact or a reference) gets no line. On a rules-8 line `check`
+prints `certainty <slug>: <claim> <level> start=<level> steps=<step>,...` per claim:
+a missing obligation narrows the claim instead of refusing the line, and the report
+states each claim's level.
+
+On a rules-8 line, run `cite <slug>` after adding a formal INDEX row: it stores
+each registry's receipt for its arXiv id or DOI - a bare DOI (`10.1109/...`), a
+`doi:` one or a `https://doi.org/` URL. A source no registry indexes records
+`unindexed_reason` and narrows its claims instead of failing the line. A registered
+metric the report leaves out is named in the report; before the run it may instead
+take a `not_reported: <metric>: <reason>` line in `protocol.md`, which is frozen
+once the run is filed. Three or more words in double quotation marks in a claim's
+`statement` are a quote, and `check` looks for them in the text `fetch` captured
+and in the receipts' abstracts, so write a paraphrase without quotation marks. A
+falsifier `check` evaluates reads `<field> <op> <number> [on <group>]` over the
+results rows; free text narrows the claims citing it (`falsifier-not-evaluable`).
+
 `claim` reads that object from stdin and appends it as one line: exit 0,
 `claim <id> recorded` (just `claim recorded` when the object carries no `id`);
 exit 1 with one `FAIL <slug>: <problem>` line per problem
@@ -157,10 +184,14 @@ rather than inventing one. `--dry-run` prints the same report and writes nothing
 `source` files one run as the experiment's receipt: it runs `orx logs <runId>`,
 writes the log to `experiments/<hypothesis>/raw/<runId>.log`, and appends the row
 `{"source": "orx:<runId>", "log": "raw/<runId>.log"}`. The experiment must already
-have its `protocol.md` on disk; `source` does not check that it is committed, so
-commit the protocol first yourself. Even then the order rule proves commit order,
-not run order. Without orx it exits 2 and says so, and it writes nothing at all
-when the run cannot be read.
+have its `protocol.md` on disk. On a rules-8 line `source` commits the capture
+itself, so it first refuses, writing nothing, while the evaluation lock, the
+arena or `protocol.md` is not committed, or the protocol holds an invalid
+number or a metric other than the locked one: commit the line first
+(`tezgah-research commit <slug> "<message>"`). On an older line it checks none
+of that, so commit the protocol first yourself. Either way the order rule proves
+commit order, not run order. Without orx it exits 2 and says so, and it writes
+nothing at all when the run cannot be read.
 
 `check` enforces the rules a session tends to skip: `protocol.md` committed
 before `results.jsonl` - decided on the commit graph, so two commits inside the
@@ -221,7 +252,7 @@ rules the domain library enforces on a compiled artifact apply here:
   command or the node - and every recorded fact in `analysis.md` points at the row
   it came from. One row is one JSON object on its own line; a file whose line three
   is prose loads in nothing. When the source is a run the engine owns, file the log
-  with `tezgah-research source`, so the row and the receipt are written together
+  with `~/.config/tezgah/bin/tezgah-research source`, so the row and the receipt are written together
   and the claim's `orx:<runId>` token resolves to something a reader can open.
 - **An input is part of the evidence: every row declares its `scope`.** `real` (the
   running system and its corpus), `fixture` (a temp HOME, a generated repository, a
@@ -317,7 +348,7 @@ cite the note on the paper or page itself beside it. The grey
 channel is allowed and often the only evidence a practice question has, so it is
 labelled and judged (`quality`) rather than skipped, and a row that records it as
 verified by fewer than two sources is reported: an unlabelled grey source is how a
-marketing claim enters a findings file as a fact. `tezgah-research migrate` writes
+marketing claim enters a findings file as a fact. `~/.config/tezgah/bin/tezgah-research migrate` writes
 the rows it can derive from the notes already saved and tells you which fields
 they do not carry.
 
@@ -334,7 +365,7 @@ they do not carry.
 
    ```text
    prediction: prompt tokens per turn drop by a third over seven runs
-   falsifier: prompt tokens per turn hold flat or rise
+   falsifier: tokens_per_turn >= 1500 on cache
    headroom: 40% of each prompt repeats the previous turn
    metric: prompt tokens per turn
    unit: tokens per turn
@@ -363,12 +394,17 @@ they do not carry.
 4. Record the raw result in `results.jsonl` with its `source`, then write what it
    means in `analysis.md`. Label each outcome CONFIRMATORY (predicted by the
    protocol) or EXPLORATORY (noticed during the run). A run the engine owns is
-   recorded with `tezgah-research source <slug> <hypothesis> --run <orxRunId>`,
+   recorded with `~/.config/tezgah/bin/tezgah-research source <slug> <hypothesis> --run <orxRunId>`,
    which files the log under `raw/` and appends the row that names it. Rows are
    append-only once committed: a correction is a new row, and `check` refuses a
    committed row changed or removed afterwards (a line opened before `rules`
    existed is warned instead, like every rule of this rule set).
-5. A negative result is a result: record what it rules out. When the line locked
+5. A negative result is a result: record what it rules out. Narrowing a claim to
+   what its evidence reaches, ending a hypothesis `inconclusive` and closing a line
+   with `close <slug> --limit "<what is left>"` are normal outcomes, not failures to
+   avoid: report each claim's certainty as `check` computes it (a claim below
+   `moderate` is exploratory and says so), and drop universal or causal wording the
+   evidence does not carry - `check` warns on it. When the line locked
    the two-gate pair (Bootstrap above), a run is a survivor only when it is inside
    the `capability_tolerance` **and** moves the `counter_metric`, and survivors are
    compared against each other on the Pareto frontier rather than by one number's
@@ -451,14 +487,14 @@ early, and spends runs only on what survived the cheaper stages.
 verbatim>"`, `--in`/`--out` (every idea traces to an `--in` item),
 `--budget "<ideas, pilots, full runs, wall time>"` and, when a number can judge a
 candidate, `--evaluator <path> --metric "<what it returns>"` (its sha256 is
-recorded). Commit it (`tezgah-research commit <slug> "arena"`) before the first
+recorded). Commit it (`~/.config/tezgah/bin/tezgah-research commit <slug> "arena"`) before the first
 idea: `check` refuses ideas or results that entered the history before the arena,
 an arena changed after it, and every stage row while the evaluator no longer
 hashes as locked - the candidate never edits its judge. An arena with no evaluator
 is judged by review only and no idea of it reaches `confirmed`. One campaign is one
 line, so the one-open-line rule holds as it is.
 
-**Ideas are rows** (`tezgah-research idea <slug>`, one JSON object on stdin): `id`
+**Ideas are rows** (`~/.config/tezgah/bin/tezgah-research idea <slug>`, one JSON object on stdin): `id`
 (`I1`, `I2`, ...), `statement` (two sentences at most), `mechanism`, `trace` (the
 `S<n>` it serves), `operator`, `generator` (`{"family", "model"}` as the host reports
 them), `parents` (required for `mutation` and `crossover`), `kill` (the result that
@@ -482,11 +518,11 @@ idea's move on purpose:
 | `mutation`, `crossover` | vary one idea, or join two (`parents`) | - |
 | `user` | an idea the person brought | - |
 
-The entries are `skills/ai-research/21-research-ideation/brainstorming-research-ideas/SKILL.md`
-and `.../creative-thinking-for-research/SKILL.md`. A closed line's dead ends
+The entries are `skills/ai-research/21-research-ideation/brainstorming-research-ideas/ENTRY.md`
+and `.../creative-thinking-for-research/ENTRY.md`. A closed line's dead ends
 (`done/`) are the first filter for a new idea.
 
-**The funnel** (`tezgah-research stage <slug> <idea> <stage> --evidence ...`); an
+**The funnel** (`~/.config/tezgah/bin/tezgah-research stage <slug> <idea> <stage> --evidence ...`); an
 idea moves forward only, each stage after the one it needs (prior art before
 screening, screening before a pilot, a pilot before a full run, a full run
 before a confirmation), or to `killed --reason` from anywhere; its stage is its
@@ -500,7 +536,7 @@ newest row:
    `literature/INDEX.jsonl` (not agent summaries only), a verdict `novel`,
    `incremental` or `known`, and one sentence on what the idea does differently.
    `known` takes `--reason` and is killed in the same append; it stays on record.
-3. `screened`: judged in `tezgah-research match <slug>` rows - pairs shown in both
+3. `screened`: judged in `~/.config/tezgah/bin/tezgah-research match <slug>` rows - pairs shown in both
    orders, two judges or more, of a model family that generated neither idea (else
    both generators' families). `board` fits a Bradley-Terry score: a prior for
    ordering the pilots, never a verdict, and `check` only warns about the judging.
@@ -516,9 +552,9 @@ Budget discipline: spend pilots only on screened ideas and full runs only on
 piloted ones, never let a ranking stand in for a pilot, and stop at the budget
 the arena names. The report says how many ideas reached piloted and promoted -
 `check` warns when it does not - because fifty ideas tested at the 5% level yield
-about 2.5 winners by chance. After a crash, `tezgah-research board <slug>` is the
+about 2.5 winners by chance. After a crash, `~/.config/tezgah/bin/tezgah-research board <slug>` is the
 whole state: every idea's stage, score and next action, and any torn append to
-re-run. Before the next campaign, `tezgah-research yield` counts per operator and
+re-run. Before the next campaign, `~/.config/tezgah/bin/tezgah-research yield` counts per operator and
 family how far ideas got, and prints the operator weights the next campaign draws
 with: uniform until something is promoted, then 80% in proportion to promoted /
 proposed and 20% kept uniform.
@@ -589,7 +625,7 @@ a finding. It reports a line with a report and no review at all, and `--strict`
 refuses it: a review is a judgement, so nothing can migrate one into existence.
 The review names its `producer` (the session that wrote the line) and its
 `reviewer`, and they differ - a line graded by the session that wrote it is not
-reviewed, so run the review as a fresh subagent or a `consult`. `findings: []`
+reviewed, so run the review as a fresh subagent or a `~/.config/tezgah/bin/consult`. `findings: []`
 warns and `--strict` refuses it, and a review scoring `exploration_integrity` or
 `methodological_rigour` above 3 while `check` refuses the line's order is refused.
 
@@ -616,19 +652,28 @@ opened under):
 |---|---|
 | `criteria.json` | `question`, `baseline_variant` (V0, the status quo or current design) and `criteria[]`, each with `id` (`K1`), `name`, `kind` (`measured` or `judged`), `direction` (`max`, `min` or `pass`), optional `threshold` and `guardrail` |
 | `variants.jsonl` | one row per variant: `id`, `title`, `artifact` (a path in the line or the repository, `git:<branch>` or `orx:<expId>`), `status` (`produced` or `dropped` with `drop_reason`), and `line` when it is an older line's deliverable |
-| `comparison.jsonl` | one row per cell: `variant`, `criterion`, `value` with its `source`, or `not_checked` with the reason; `rater` on a judged cell. Append with `tezgah-research compare <slug> <id>` (one JSON object on stdin), which refuses what `check` refuses |
-| `decision.md` | `chosen: V2`, one line per rejected id naming the criterion id that ruled it out, and `flip:` - the result that would reverse the choice |
+| `comparison.jsonl` | one row per cell: `variant`, `criterion`, `value` with its `source`, or `not_checked` with the reason; `rater` on a judged cell. Append with `~/.config/tezgah/bin/tezgah-research compare <slug> <id>` (one JSON object on stdin), which refuses what `check` refuses |
+| `decision.md` | `recommended: V2` (the line's pick), one line per rejected id naming the criterion id that ruled it out, and `flip:` - the result that would reverse the choice; `chosen:` and `owner:` only once the owner picks |
 
 `check` refuses: fewer produced variants than the deliverable takes; two produced
 files with the same content (a renamed copy is not an alternative); `criteria.json`
 not committed before the first `comparison.jsonl` commit; a comparison row changed
 after it was committed; a missing cell once `decision.md` exists or the line is
-delivering; a `chosen` that is not a produced variant, a rejected variant with no
-criterion, no `flip:`; and a chosen variant another one beats or ties on every
-numeric criterion. A judged cell with fewer than two raters warns (`--strict`
-refuses). A design or plan (and an analysis on a line before rules 5) with no
-`decisions/` warns while the line runs, is refused once it delivers, and keeps
-the line open.
+delivering; a pick (`chosen:`, else `recommended:`) that is not a produced
+variant, a rejected variant with no criterion, no `flip:`; and a picked variant
+another one beats or ties on every numeric criterion. A judged cell with fewer
+than two raters warns (`--strict` refuses). A design or plan (and an analysis on
+a line before rules 5) with no `decisions/` warns while the line runs, is refused
+once it delivers, and keeps the line open.
+
+The line recommends; the owner chooses. Choosing a variant or option a research,
+analysis or review recommends is the owner's call, so a rules-9 line writes
+`recommended:` and never `chosen:` itself - a `chosen:` with no `owner:` line
+fails `check`. Report the recommendation and wait for the answer; building it
+waits too. When the owner answers, record their words:
+`~/.config/tezgah/bin/tezgah-research choose <slug> <decision> <variant> --ack
+"<the owner's words>"` writes `chosen:` and `owner:`, on an open or a done line.
+`conclude` names each recommendation still waiting for the owner.
 
 When the variants are code or config, they are sibling orx nodes under one head
 node (orx cardinal rule 4: fan within a round, then descend onto the winner), and
@@ -638,15 +683,19 @@ deliverable (`"line": "<old>"`); `init` refuses a line asking an existing line's
 question without it, and `check` refuses a line sharing another's
 `deliverable.path` that does not supersede it.
 
-A line that cannot finish is closed on purpose: `tezgah-research close <slug>
+A line that cannot finish is closed on purpose: `~/.config/tezgah/bin/tezgah-research close <slug>
 --limit "<what is left and why>"` concludes it, writes the reasons it was still open
 into `state.json` `closed` and `log.md`, seals its experiments' file hashes
 (`order_seal`), and stops it counting as open; `conclude` seals the same
 way, and an edit after the seal fails `check`. The no-slug `check` reads a done
 line by its seal alone and counts it on one line; its other errors show in
 `check <slug>` and `check --all-lines`. `init --allow-open` is refused
-while an open line has `check` errors. A line moves to another checkout with
-`import`, never as a copy: a copy loses the order proof.
+while an open line has `check` errors, other than a criterion whose verdict is
+still `pending` (a line in flight). A line another session is running is not this
+session's to fix or close: when a refusal names one, stop and ask the owner -
+never a way around a tezgah refusal (another folder, a hidden dir). A hidden dir
+under `research/` is not a line: `check` and `status` fail it. A line moves to
+another checkout with `import`, never as a copy: a copy loses the order proof.
 
 Finally, a `## Patterns` bullet names what it generalises from - a claim id, a
 `literature/` note or a run - because a pattern is the one finding a reader carries
@@ -704,7 +753,7 @@ The two-loop rhythm, the workspace layout and the six review dimensions adapt th
 orchestration layer of Orchestra Research's MIT-licensed `AI-research-SKILLs`
 library (its `autoresearch`, `ara-rigor-reviewer` and `ara-research-manager`
 skills) to tezgah's contract: the execution engine here is OpenResearch, the
-reporting language is the contract's, the checks are `tezgah-research`'s own, and
+reporting language is the contract's, the checks are `~/.config/tezgah/bin/tezgah-research`'s own, and
 nothing is copied verbatim. The scoring anchors, the finding record, the citation
 workflow and the figure rules come from the same library, which now ships whole
 under the `ai-research` skill.

package/skills/rl-env/SKILL.md

@@ -1,18 +1,23 @@
 ---
 name: rl-env
 description: >
-  Use when the task is to build, port or reason about an RL training environment
-  - the vendored FineEnvs set for authoring one across OpenEnv (HTTP + MCP,
-  Hugging Face), OpenReward / ORS (a reward with each tool call), Verifiers
-  (Prime Intellect, in-process tools and rubrics) and NeMo Gym (HTTP plus a
-  post-episode /verify grader), with the orchestrator that interviews the user
-  and ports one description across all four, including prompts like "make an env
-  where the agent does X" or "wrap my game in OpenEnv". Read one entry, never
-  the tree.
+  Use when building an RL training environment; pekiştirmeli öğrenme, ortam;
+  port to OpenEnv, Verifiers, NeMo Gym. Not for model training - use
+  `ai-research`.
 ---
 
 # rl-env: authoring an RL environment
 
+## When to use
+
+Use when the task is to build, port or reason about an RL training environment -
+the vendored FineEnvs set for authoring one across OpenEnv (HTTP + MCP, Hugging
+Face), OpenReward / ORS (a reward with each tool call), Verifiers (Prime
+Intellect, in-process tools and rubrics) and NeMo Gym (HTTP plus a post-episode
+/verify grader), with the orchestrator that interviews the user and ports one
+description across all four, including prompts like "make an env where the agent
+does X" or "wrap my game in OpenEnv". Read one entry, never the tree.
+
 Five upstream skills, vendored byte-for-byte from FineEnvs at the revision
 `SOURCE` names (Apache-2.0; the repository's root `NOTICE` records what changed,
 which is nothing but the vendoring itself). They are instructions, not
@@ -33,11 +38,18 @@ anything, and never claim a training result this skill cannot produce.
 
 | Entry | What it produces |
 |---|---|
-| `rl-env-from-description/SKILL.md` | The orchestrator: a clarifying interview (`references/interview.md`), then the same description ported to all four frameworks - start here unless the user has already named a framework |
-| `generate-openenv-env/SKILL.md` | OpenEnv (Hugging Face): HTTP + MCP, tools discovered through `list_tools()`, an optional Gradio UI, a Docker container or HF Space at the end |
-| `generate-ors-env/SKILL.md` | OpenReward (ORS): HTTP + REST + SSE, a reward inline with each tool call instead of after the episode, task-spec sessions, train/val/test splits |
-| `generate-verifiers-env/SKILL.md` | Verifiers (Prime Intellect): in-process tools with no HTTP server, composable rubrics, the shortest path from a prototype to a TRL `GRPOTrainer` |
-| `generate-nemo-gym-env/SKILL.md` | NeMo Gym (NVIDIA): tools as `app.post()` endpoints with cookie sessions, a post-episode `/verify` grader, Ray-based orchestration |
+| `rl-env-from-description/ENTRY.md` | The orchestrator: a clarifying interview (`references/interview.md`), then the same description ported to all four frameworks - start here unless the user has already named a framework |
+| `generate-openenv-env/ENTRY.md` | OpenEnv (Hugging Face): HTTP + MCP, tools discovered through `list_tools()`, an optional Gradio UI, a Docker container or HF Space at the end |
+| `generate-ors-env/ENTRY.md` | OpenReward (ORS): HTTP + REST + SSE, a reward inline with each tool call instead of after the episode, task-spec sessions, train/val/test splits |
+| `generate-verifiers-env/ENTRY.md` | Verifiers (Prime Intellect): in-process tools with no HTTP server, composable rubrics, the shortest path from a prototype to a TRL `GRPOTrainer` |
+| `generate-nemo-gym-env/ENTRY.md` | NeMo Gym (NVIDIA): tools as `app.post()` endpoints with cookie sessions, a post-episode `/verify` grader, Ray-based orchestration |
+
+Each entry file is upstream's `SKILL.md` renamed `ENTRY.md`, bytes unchanged, so a
+host that lists every `SKILL.md` below its skills directory does not list it; a
+body that says `SKILL.md` means its own `ENTRY.md`. Hosts no longer list the four
+ports as skills either, so where the orchestrator says "trigger `generate-*-env`
+skill" or "trigger the framework-specific skill", read that entry's `ENTRY.md`
+(`generate-openenv-env/ENTRY.md` and so on) instead.
 
 Each of the four ports ships its own `references/architecture.md`; the
 orchestrator ships one reference per framework beside its interview notes. The

package/skills/rl-env/SOURCE

@@ -3,7 +3,9 @@
 Vendored from https://github.com/adithya-s-k/FineEnvs at
 `26ab9c60915005b6f536968ac0928482bb18c0f8` (2026-10-01), Apache-2.0 licence (the
 repository's root `LICENSE`). Every body below is byte-for-byte upstream,
-frontmatter included, at its upstream path under `.claude/skills/`. Checkout for
+frontmatter included, at its upstream path under `.claude/skills/`, with one
+rename: each entry's `SKILL.md` is `ENTRY.md` here, so a host that lists every
+`SKILL.md` below its skills directory (codex, Cursor) does not list it. Checkout for
 a re-vendor: `git clone https://github.com/adithya-s-k/FineEnvs && git -C <clone>
 checkout 26ab9c60915005b6f536968ac0928482bb18c0f8`.
 
@@ -25,15 +27,15 @@ what was vetted is visible.
 
 | file | upstream path | sha256 |
 |---|---|---|
-| `generate-nemo-gym-env/SKILL.md` | `.claude/skills/generate-nemo-gym-env/SKILL.md` | `b051de706519973d23e1acb9211f7dee18a681b2b94f0fdc132c6cab0c035f3e` |
+| `generate-nemo-gym-env/ENTRY.md` | `.claude/skills/generate-nemo-gym-env/SKILL.md` | `b051de706519973d23e1acb9211f7dee18a681b2b94f0fdc132c6cab0c035f3e` |
 | `generate-nemo-gym-env/references/architecture.md` | `.claude/skills/generate-nemo-gym-env/references/architecture.md` | `2329797c0881697c56d8dfee62396fb858bcfac3c313840155b23acf6720a77c` |
-| `generate-openenv-env/SKILL.md` | `.claude/skills/generate-openenv-env/SKILL.md` | `f8d7d65ec85ee228bf8ffe15df72492c5043541c853f287c5159d7b3eea383c9` |
+| `generate-openenv-env/ENTRY.md` | `.claude/skills/generate-openenv-env/SKILL.md` | `f8d7d65ec85ee228bf8ffe15df72492c5043541c853f287c5159d7b3eea383c9` |
 | `generate-openenv-env/references/architecture.md` | `.claude/skills/generate-openenv-env/references/architecture.md` | `6ba32c5a1498c6660f79db3feeb0f49226344054bae7cdc1d84d8440147d5509` |
-| `generate-ors-env/SKILL.md` | `.claude/skills/generate-ors-env/SKILL.md` | `68385ef145bdcff61d2878be6db1d6b9652581ba7a5a05369ce6a61a6332ace5` |
+| `generate-ors-env/ENTRY.md` | `.claude/skills/generate-ors-env/SKILL.md` | `68385ef145bdcff61d2878be6db1d6b9652581ba7a5a05369ce6a61a6332ace5` |
 | `generate-ors-env/references/architecture.md` | `.claude/skills/generate-ors-env/references/architecture.md` | `ee87650a409a8ae375935a99daa9a5141d1fae514a1d05abcd87293759e708e4` |
-| `generate-verifiers-env/SKILL.md` | `.claude/skills/generate-verifiers-env/SKILL.md` | `afd9c6d0521735acfed0f308a133e33a6b3d24534e79aabb659f8f20ccfc7a64` |
+| `generate-verifiers-env/ENTRY.md` | `.claude/skills/generate-verifiers-env/SKILL.md` | `afd9c6d0521735acfed0f308a133e33a6b3d24534e79aabb659f8f20ccfc7a64` |
 | `generate-verifiers-env/references/architecture.md` | `.claude/skills/generate-verifiers-env/references/architecture.md` | `babda38780715a82f9b481ef4469221c8752befb5f9bf1dc7d9093f2b05d634e` |
-| `rl-env-from-description/SKILL.md` | `.claude/skills/rl-env-from-description/SKILL.md` | `fb2b92b92988655b4c4ddae5cfe07e58f18d4105fef4e21058925e48a680438b` |
+| `rl-env-from-description/ENTRY.md` | `.claude/skills/rl-env-from-description/SKILL.md` | `fb2b92b92988655b4c4ddae5cfe07e58f18d4105fef4e21058925e48a680438b` |
 | `rl-env-from-description/references/interview.md` | `.claude/skills/rl-env-from-description/references/interview.md` | `8284ef8b809d6bcbbd76c9bee63baf1e23aae80a4f089d7daed02ec6cc285e9a` |
 | `rl-env-from-description/references/nemo_gym.md` | `.claude/skills/rl-env-from-description/references/nemo_gym.md` | `48e2b011ad13454e38245dcb791a98a6496c1ea53cc909895e2350d50a303e74` |
 | `rl-env-from-description/references/openenv.md` | `.claude/skills/rl-env-from-description/references/openenv.md` | `4550337161bac2e08fbf5ca6a5b58ca55c422cc06169669a784a9eb974e35bd6` |