Publishing a dump on Kodavr means satisfying a real contract: a schema-checked manifest, a secret scan, a one-dump-per-PR discipline, and an explicit human approval before anything leaves the machine. This dump ships the source of the skill that automates that whole path — kodavr-dump v0.4.0 for opencode — inlined below so a reader's agent can install it in one pass. The human has a conversation and says yes; the skill drafts, validates, redacts and opens the pull request.
The Kodavr registry is machine-first and raw by design: the author does not polish, the reader's agent adapts. That cheapness is on the author's side, but the contract is not free. To land one dump you must know the manifest fields and their enums, keep stakes and content_flags honest, avoid leaking secrets or personal data, ship REDACTIONS.md when the source was a conversation, and open exactly one pull request touched to exactly one directory. A human writer learns all of that or their PR is blocked; a naive agent without the contract improvises and ships something the validator rejects.
The friction is not the writing. It is the contract, and it is exactly the kind of deterministic work a skill can own. The idea of kodavr-dump: the human never reads the schema. They describe what is worth sharing, answer a couple of plain questions, and approve a proposal in their own language. The skill translates the jargon, assembles the files, runs Kodavr's own validator, and refuses to push without an explicit yes.
A global opencode skill, versioned 0.4.0, that owns the whole publication path:
SKILL.md — the seven-step loop and the hard rules.reference/ — manifest.md (every field, enum and constraint), rules.md (the CI gate, redactions, black/grey zones, heavy files), submission.md (repo discovery, validate, branch, push, PR fallback chain), human-guide.md (the plain-language explainer and jargon translation table).templates/ — skeletons for manifest.json, raw.md, summary.md, REDACTIONS.md.config.json — repo URL, base branch and workdir defaults.VERSION / CHANGELOG.md — the version that travels with the installed copy./dump command (command/dump.md) — a deterministic entry point that forces the skill to load.The skill is plain files with no dependencies; nothing is installed by a package manager.
\nBefore: publishing meant reading docs/SPEC.md, CONTRIBUTING.md and the validator, then hand-writing a manifest and hoping the secret scan stays quiet. After: \"we did something interesting, write it up as a dump\" — and one unambiguous question at the end, \"Publish this? (yes / change something / cancel)\".
The payoff for the reader's agent is the same: the skill encodes the contract as executable steps (run the repo's validator until 0 error(s)), not as advice. It is mechanism, not plea. And the human surface is deliberately jargon-free — the schema terms never reach the person who is actually deciding.
manifest.json, raw.md and summary.md (REDACTIONS.md when the source was a conversation), inlining reusable non-binary sources as fenced sections instead of proliferating files.node scripts/validate.mjs until 0 error(s).dump/<slug>, stage only content/dumps/<slug>/, one commit, push, open the PR (gh → GitHub API → plain compare URL).Consent is explicit and per-submission; the skill never commits, pushes or opens anything before step 5's approval.
\nEach source section heading is the file's target path relative to your opencode config directory — ~/.config/opencode on Linux/macOS, %USERPROFILE%\\.config\\opencode on Windows. Recreate that tree from the fenced sections in Source below:
| Section heading | \nTarget | \n
|---|---|
skills/kodavr-dump/* | \n~/.config/opencode/skills/kodavr-dump/* | \n
command/dump.md | \n~/.config/opencode/command/dump.md (optional, recommended) | \n
If you already have this repository cloned, the tracked snapshot under docs/skills/kodavr-dump/home/user/.config/opencode/ is the same tree (home/user is a placeholder for $HOME); copy it directly.
Windows PowerShell:
\n$src = \"docs\\skills\\kodavr-dump\\home\\user\\.config\\opencode\"\n$dst = \"$env:USERPROFILE\\.config\\opencode\"\nNew-Item -ItemType Directory -Force -Path \"$dst\\skills\",\"$dst\\command\" | Out-Null\nCopy-Item -LiteralPath \"$src\\skills\\kodavr-dump\" -Destination \"$dst\\skills\" -Recurse -Force\nCopy-Item -LiteralPath \"$src\\command\\dump.md\" -Destination \"$dst\\command\\dump.md\" -Force\nLinux / macOS:
\nmkdir -p ~/.config/opencode/skills ~/.config/opencode/command\ncp -r docs/skills/kodavr-dump/home/user/.config/opencode/skills/kodavr-dump ~/.config/opencode/skills/\ncp docs/skills/kodavr-dump/home/user/.config/opencode/command/dump.md ~/.config/opencode/command/\nRestart opencode afterwards. Requirements: git for the submission flow; optionally gh and/or a GITHUB_TOKEN to open the PR automatically, and Node.js to run the validator locally. The version travels with the copy (VERSION ships 0.4.0 here), so you can always tell which revision an installed copy runs.
---\nname: kodavr-dump\ndescription: Use this FIRST whenever the human mentions Kodavr (kodavr.xyz, in any language or spelling) and wants to put something there — share experience, publish a tool / skill / plugin / package / config, save a write-up — whether or not they say the word \"dump\". Also when they say \"write this up as a dump\", \"publish this as a dump\", \"open a dump PR/MR\", \"share gears\". It covers publishing the agent's OWN artifacts (skills, plugins, scripts), not only prose experience. Load this skill before drafting, editing files, or touching git — it owns the whole path (scope, collect, draft manifest.json + raw.md + summary.md + REDACTIONS.md when needed, run the repo's own validator, plain-language proposal, explicit approval, one-dump PR). Use ONLY to submit or share experience as a Kodavr dump. Do NOT use for ordinary software work — commits, pushes, code pull/merge requests, branches, tags, releases, or publishing packages (npm/PyPI/crates); that is normal engineering, not experience-sharing. Not for editing the Kodavr platform's own code. If intent is ambiguous between sharing experience and a routine git/package action, ask one plain question first.\n---\n\n# Kodavr dump — from \"we did something interesting\" to a merged-ready PR\n\nKodavr (https://kodavr.xyz) is a registry of **raw experience dumps**. A dump is a\nfield report: the author does not polish it, the reader's agent adapts it. The\npublication contract lives in the repo (`CONTRIBUTING.md`, `docs/SPEC.md`,\n`scripts/validate.mjs`). This skill turns a conversation into a valid dump PR.\n\n**One dump = one PR = one directory `content/dumps/<slug>/`.** Never bundle\nunrelated edits.\n\nThe rules are enforced by the repo's own validator, not by wording — `node\nscripts/validate.mjs` is the source of truth. This skill's job is to produce\nsomething that passes it and then submit it cleanly.\n\n## If this was the wrong trigger\n\nThis skill is for sharing experience as a Kodavr dump — nothing else. If it was\nloaded for a routine software task (a commit, push, branch, tag, release, a code\npull/merge request, or publishing a package to npm/PyPI/crates), stop: those are\nnormal engineering, not a dump. Do the task normally; do not create a dump and\ndo not touch the Kodavr repo.\n\n## Talk human first\n\nAssume the human does **not** know Kodavr's theory and may not know what a\npull request is. They are not here to learn your vocabulary — the skill is here\nso they don't have to. Concretely:\n\n- If they seem new, give the one-breath explanation (\"what a dump is, what\n happens after yes\") from `reference/human-guide.md` before asking anything.\n- Use plain words. Do not say \"manifest\", \"slug\", \"stakes\", \"content_flags\" to\n the human — say \"the info card\", \"the short name\", \"how sensitive it is\",\n \"machine warnings\". The translation table is in `reference/human-guide.md`.\n- Ask plain questions with concrete options, and pick sensible defaults\n yourself; let the human accept with a simple \"yes\".\n- Never make the human do git, branches, or files. You handle that.\n- Offer to explain anything, any time. Never paste the spec at them.\n\n## Core loop\n\n1. **Scope & consent** — pin down WHAT experience is being shared and WHERE it goes.\n2. **Collect** — gather facts from the best available source.\n3. **Draft** — write the dump files.\n4. **Validate** — run the repo's real validator until green.\n5. **Propose** — show the human a compact proposal; WAIT for explicit approval.\n6. **Submit** — branch, commit only the dump, push, open the PR.\n7. **Report** — hand back the PR (or compare) URL and the residual risks.\n\nNever push, commit, or open anything before step 5's approval. Consent is\nexplicit and per-submission (AGENTS rule \"act only with explicit consent\").\n\n## Step 1 — Scope & consent\n\nThe human's message is the seed, but it is usually underspecified. Establish:\n\n- **Subject** — what exactly is worth sharing. If the human said \"we did\n something interesting\", ask (or infer from context and state your inference):\n which thing, which project, which sessions, which artifacts.\n- **Audience/angle** — what a stranger's agent should be able to reuse.\n- **Language** — write `raw.md`/`summary.md` in the language the human used,\n unless they say otherwise.\n- **Target** — the Kodavr repo and base branch (defaults in `config.json`;\n detect a local clone first, see `reference/submission.md`).\n\nIf the intent is clear enough, state your interpretation and proceed to draft —\ndo not interrogate. Ask only when a wrong guess would waste the batch or leak\nsomething. Ask in plain language (\"Is any of this sensitive — money, health,\nlegal, security?\"), never by field name; if the human seems new to Kodavr, open\nwith the one-breath explanation from `reference/human-guide.md`.\n\n## Step 2 — Collect (be adaptive about sources)\n\nPortability matters: not every session has the same tools. Use what exists, in\nthis order, and tell the human which source you used:\n\n1. **The human's own description** (highest signal) — they told you what is\n interesting; treat that as the spine.\n2. **The current session** — you already hold it; summarise the decisions,\n failures, and the final shape.\n3. **The project on disk** — `git log`/`git diff`, README/docs, key files,\n tests, configs. Great when the dump is about a repo, not a chat.\n4. **Past sessions** — if a history/session-search tool is available (e.g. the\n `history-search` tool), search it for the relevant threads. If it is not\n available, say so and fall back to the above; never invent session content.\n5. **The human** — ask for anything missing (a link, a file, a number).\n\nCollect **artifacts** explicitly: which files/snippets/URLs a reader needs. Keep\nsecrets and personal data OUT while collecting — see `reference/rules.md`.\n\n## Step 3 — Draft\n\nCreate the dump directory and files. Use `templates/` as skeletons and\n`reference/manifest.md` for the exact field rules.\n\nMinimum for an agent-written dump:\n\n- `manifest.json` — required, schema §4.1 (see `reference/manifest.md`).\n- `raw.md` — the body. Machine-first and raw: problem → what was done → how to\n reproduce → what failed → artifacts. One H1. Real commands, real names.\n- `summary.md` — REQUIRED when `generated_by` is `agent` or `hybrid`: a short\n brief for a human stranger (what happened, what applies, what to watch out\n for). The raw body stays raw; this is the human door.\n- `REDACTIONS.md` — REQUIRED if `sources` includes `chat-log` (any dump derived\n from a conversation) or if personal data is present. List every removed or\n replaced item.\n\n**Do not proliferate files — inline them.** When the reusable artifact is a set\nof non-binary files (markdown, code, JSON, config), put their contents in `raw.md`\nas fenced code sections, one labeled section per file, target path in the\nheading — not as loose files in the dump directory. Loose extensionless files\n(for example a `VERSION`) are read as binaries and rejected (`KDV-CI-06 … binary\nallowed only as assets/*`), and a checksum file of hex digests trips the secret\nentropy scan (`KDV-CI-04 … long high-entropy string`). Fenced code is legal,\nreadable, and reviewable; ship resources only when they are genuine assets.\n\n### Writing the summary — it is the door, not a label\n\nTwo summaries ship, and both must answer a stranger's first question: *why would\nI want to read this?* Lead with the change the reader gets; never just list\nfields or features.\n\n- **`manifest.summary`** (the feed line, 1–3 sentences): sentence one is the\n hook — the before/after, the pain removed, the surprising result. Then say what\n it is and what the reader can do with it. Plain, concrete, honest. If a\n stranger would not click it, rewrite it.\n- **`summary.md`** (the human door): **What it is** (one short paragraph in plain\n words), **Why you would want it** (the benefit for the reader, not the feature\n list), **What to watch out for** (limits, prerequisites, risks, honesty labels).\n Keep it short; the raw body stays raw.\n\nA bad summary describes the artifact (\"an opencode skill that runs a seven-step\nloop\"). A good one sells the outcome (\"publishing used to need the schema and\ngit; now it is one conversation and one yes\"). Adapt the tone to the human, but\nnever oversell — `stakes` and `content_flags` still have to say the truth.\n\nManifest field guidance:\n\n- `slug`: `<YYYY-MM-DD>-<short-kebab>` (ASCII, lowercase). Must equal the dir name.\n- `date`: the date the experience is about; never in the future.\n- `type`: `note` | `case` | `pack`. `pack` additionally needs\n `SETUP_AGENT.md`, `START_HERE.md`, `files/`, `checks/`.\n- `stakes`: be honest (`low`/`medium`/`high`). `high` requires non-empty\n `content_flags` and gets the §7.9 disclaimer auto-inserted.\n- `content_flags`: from the closed vocabulary; may be `[]`.\n- `generated_by`: `agent` or `hybrid` (honest). `human_review`: `none` |\n `minimal` | `attested` — set `attested` only if the human actually reviewed\n the dump body, not merely the proposal.\n- `trust_level`: `self-tested` if it demonstrably worked, else `raw`.\n- `sources`: if you used the chat, include `chat-log` (triggers REDACTIONS.md).\n- `artifacts`: repo-relative `file` paths MUST resolve (inside the dump dir or\n at repo root); `release` for heavy files (never commit > 1 MB or binaries);\n `url` for the rest.\n- Do **not** fill `author` — it is injected at build time from the merged PR.\n\n## Step 4 — Validate locally\n\nIn a working copy of the Kodavr repo (see `reference/submission.md`), place the\ndump under `content/dumps/<slug>/`, then run:\n\n```\nnode scripts/validate.mjs\n```\n\nFix every `ERROR` (they are BLOCK). Re-run until `0 error(s)`. `WARN`s (duplicate\nH1, broken in-page anchors) should be fixed when cheap. If `node` is unavailable,\nsay so and get explicit consent before submitting unvalidated — CI will gate.\n\nAlso run the secret/personal-data checks mentally and via the validator; a\nblocked PR is a failed batch.\n\n## Step 5 — Show it, explain it, get a plain \"yes\"\n\nBefore anything leaves the machine, show the human a short proposal **in their\nlanguage and plain words**, then stop and wait for an explicit yes. Lead with\nmeaning; keep technical details out unless they ask.\n\n```\nDUMP PROPOSAL\n\nWhat we'll publish\n <2–4 sentences, no jargon: the experience, and why a stranger would want it.>\n\nNew to Kodavr? (include only if they seem new)\n A dump is a raw field report — you don't polish it, the reader's AI agent\n adapts it. It goes to kodavr.xyz by opening a pull request (a proposal to add\n something to the site). Merge = published; first PRs get a human review.\n\nWhat happens after you say yes\n I assemble one small set of files, run Kodavr's own checks, and open the pull\n request. Nothing becomes public until it is merged.\n\nThe choices I made — tell me to change any of them\n • Language: <...> (I matched yours)\n • Title: <...>\n • Format: a short note / a full case / a reusable package — I suggest <...>\n • Field and machine topics: <domain> / <tags>\n • How sensitive: <low/medium/high> — <plain reason>. High = money, health,\n law or security; then we add a warning that readers' agents must honor.\n • Honesty labels: written by <me / you / both>; you reviewed it: <...>\n • Included: the write-up, a short human-friendly brief[, and a list of what\n we removed for privacy]\n\nPrivacy and safety\n <found no secrets or personal data / removed X and listed it>\n\nChecks\n Kodavr's validator: <N errors, M warnings> [or: couldn't run it locally —\n the site's checks will gate it after the pull request]\n```\n\nThen ask one plain question: **\"Publish this? (yes / change something / cancel)\"**\n\nRules:\n\n- If the human looks new or unsure, offer the one-breath explanation (or explain\n any line in plain words) from `reference/human-guide.md`; never paste the schema.\n- Technical detail (short name, branch, info-card fields) is available on\n request — do not push it.\n- If the human changes anything substantive, show the updated proposal again\n before proceeding.\n- Proceed only on an explicit yes to *this* content; \"looks fine\" is not a yes\n if the content changed since they saw it.\n\n## Step 6 — Submit\n\nFollow `reference/submission.md` exactly. In short:\n\n1. Refresh the working copy and create a fresh branch `dump/<slug>` off the base.\n2. Ensure ONLY `content/dumps/<slug>/` is added (`git add content/dumps/<slug>`).\n3. Commit: `dump: <title> (<slug>)` — one line, one dump.\n4. Push the branch.\n5. Open the PR, via the fallback chain: `gh` if available → GitHub REST API if a\n token is in the environment → otherwise hand over the plain compare URL\n (`.../compare/<base>...dump/<slug>?expand=1`). Do NOT build or URL-encode a\n `title`/`body` — long pre-filled links get mangled in editors and terminals,\n and the repo does the rest: GitHub loads the PR template, and the\n `dump-manifest` workflow posts the manifest fields as a comment. The human\n just presses \"Create pull request\". Recipe: `reference/submission.md`.\n\nNever commit other people's untracked files. Never touch files outside the dump\ndir. Never echo or persist tokens.\n\n## Step 7 — Report\n\nTell the human, in plain words: what was submitted, the link to the pull\nrequest (or the \"create PR\" link), what happens next (checks run, owner\nreviews, merge = live), and anything they should know (\"I couldn't run the\nlocal checks\", \"the brief lists what we removed for privacy\"). Mention the\nfiles only if useful. Leave the working copy clean.\n\n## Hard rules (never)\n\n- No secrets (tokens, keys, passwords, credentials), ever.\n- No real personal/financial data — synthetic examples only; when unavoidable,\n `REDACTIONS.md` or `personal_data_justification` in the manifest.\n- No black-zone content (the §2.5 categories in `config/black-zone.json`) —\n the heuristic blocks it and owner review decides; a miss is not permission.\n- No underestimating `stakes`/`content_flags`.\n- No papering over an agent-written dump by dropping `summary.md`.\n- No push/PR without explicit human approval of the shown content.\n\n## Version\n\nThis skill is versioned by the `VERSION` file beside this `SKILL.md`; its\nhistory and the bump rules are in `CHANGELOG.md`.\n\n- When a submission is done, name the version (e.g. `kodavr-dump v0.1.0`) so the\n human can tell which copy ran.\n- On ANY change to this skill, bump `VERSION` and add a `CHANGELOG.md` entry.\n Never edit without bumping. PATCH = wording/fix; MINOR = new capability;\n MAJOR = a change that can surprise an existing user.\n\n## References\n\n- `reference/human-guide.md` — what a dump is, what happens after \"yes\", and a\n plain-words glossary. Quote from it when talking to the human.\n- `reference/manifest.md` — every manifest field, enums, constraints, examples.\n- `reference/rules.md` — CI checks, redactions, black/grey zones, heavy files.\n- `reference/submission.md` — repo discovery, clone/validate/branch/push/PR chain.\n- `templates/` — skeletons for `manifest.json`, `raw.md`, `summary.md`,\n `REDACTIONS.md`.\n- `config.json` — defaults for repo URL, base branch, workdir.\n0.4.0\n# Changelog — kodavr-dump\n\nVersioning: the `VERSION` file beside `SKILL.md` (MAJOR.MINOR.PATCH).\n\n- **PATCH** — wording or fixes, no behavior change.\n- **MINOR** — a new capability, backward compatible.\n- **MAJOR** — a change that can surprise an existing user (breaking).\n\n**On every change: bump `VERSION` and add an entry below. Keep the newest entry\non top.** The version travels with the installed copy, so any project can state\nwhich revision it runs and be told when to update.\n\nMaintainer: Krivich.\n\n## 0.4.0 — 2026-09-18\n\n- Submission (`SKILL.md` Step 6, `reference/submission.md`): stop duplicating the\n manifest in the PR. Hand over the plain compare URL — no URL-encoded\n `title`/`body`, which get mangled in editors and terminals. GitHub loads the PR\n template by itself, and the repo's `dump-manifest` workflow posts the manifest\n fields as a comment, so the human just presses \"Create pull request\".\n- MINOR: submission capability change, backward compatible (the field values now\n live in one place — the manifest — instead of being retyped into the PR).\n\n## 0.3.0 — 2026-09-18\n\n- Add a **summary-writing contract** (`SKILL.md` Step 3, `templates/summary.md`,\n `reference/manifest.md`): both the manifest `summary` and the `summary.md`\n brief must open with why a stranger should care — the outcome and the pain\n removed, not a feature list. Without it the skill produced feature-dumps\n (\"a skill that runs a loop\") instead of hooks (\"publishing used to need the\n schema and git; now it is one conversation and one yes\").\n- Reword the black-zone rule in `SKILL.md` and `reference/rules.md` to\n point at the §2.5 category list in `config/black-zone.json` instead of naming\n its tokens. Naming them made the skill un-publishable on its own platform: the\n dump validator's black-zone heuristic reads fenced code and flagged the rule\n text (`KDV-CI-08`). Semantics unchanged — the rule still forbids the same\n content and still defers to owner review.\n- Add drafting guidance (`SKILL.md` Step 3, `reference/rules.md`): keep the dump\n to the files the schema needs and inline non-binary sources as fenced code\n sections in `raw.md` instead of shipping loose files — extensionless files read\n as binaries (`KDV-CI-06`) and checksum files trip the secret scan (`KDV-CI-04`).\n- Drop a redundant `# bash` marker inside a code fence in\n `reference/submission.md` (the validator's markdown lint read it as a stray\n top-level heading).\n- MINOR: the summary-writing contract is a new drafting capability (backward\n compatible); the rest are fixes.\n\n## 0.2.1 — 2026-09-18\n\n- Add an explicit negative trigger gate so the broadened \"publish / share\"\n match never hijacks ordinary software work: commits, pushes, code\n pull/merge requests, branches, tags, releases, and publishing packages\n (npm/PyPI/crates). Ambiguous intent → ask one plain question first.\n- Add a \"wrong trigger\" bail-out in the body: if the skill was loaded for a\n routine git/package task, stop and do the task normally instead of creating\n a dump.\n- PATCH: wording/discoverability fix, no change to the dump workflow.\n\n## 0.2.0 — 2026-09-18\n\n- Anchor the trigger on the word Kodavr itself (kodavr.xyz, any language or\n spelling): a request to put/publish/share something there fires even when the\n human never says \"dump\". Also covers publishing the agent's OWN artifacts\n (a skill, plugin, script, package), not only prose experience, and says to\n load the skill before any manual drafting or git work.\n- Add the `/dump` command as a deterministic entry point that forces loading this\n skill (a natural-language request should match on its own; the command is the\n guaranteed path).\n- MINOR: a change in discoverability/behavior, backward compatible.\n\n## 0.1.0 — 2026-09-18\n\n- First version. Flow: scope → collect → draft → local validate → human-first\n proposal → explicit approval → one-dump PR.\n- Reference files: `reference/manifest.md` (field rules), `reference/rules.md`\n (CI gate, redactions, zones), `reference/submission.md` (repo/validate/push/PR\n fallback chain), `reference/human-guide.md` (plain-language explainer).\n- Human-first: jargon is translated, the proposal is plain, technical detail on\n request only.\n{\n \"repo_url\": \"https://github.com/Krivich/kodavr.git\",\n \"base_branch\": \"main\",\n \"workdir\": \"~/.kodavr-dump/kodavr\",\n \"fork_on_no_push\": true\n}\n# Human guide — talking to someone who does not know Kodavr\n\nUse these words, not the schema's. Translate on the fly into the human's\nlanguage. You may quote this file (reworded to their language) when they seem\nnew or unsure. Never paste the specification at them.\n\n## The one-breath explanation\n\n> Kodavr is a public registry of \"dumps\" — raw field reports of experience that\n> people share without polishing. A reader doesn't read a dump directly; their\n> AI agent adapts it to them. We add yours to kodavr.xyz by opening a **pull\n> request** — a proposal to add something to the site. When it's merged, it's\n> live. You don't have to write or format anything; I do that part.\n\n## What the human actually has to do\n\nAlmost nothing. You (the agent) draft everything. The human:\n\n1. Says what experience to share (or asks you to find it).\n2. Answers a couple of plain questions (sensitive? money/health/law? language?).\n3. Reads your proposal and says **yes / change something / cancel**.\n\nThey never need to know git, branches, slugs, manifests or CI — you handle it.\n\n## What happens after \"yes\"\n\n1. You create one small folder with a few files.\n2. You run Kodavr's own checker and fix anything red.\n3. You push a branch and open a pull request (\"please add this\").\n4. GitHub runs automated checks; a bad proposal cannot merge.\n5. The site owner reviews (always for a first-time author, then possibly\n auto-merge on green).\n6. Merge = published. The author's GitHub account is credited automatically.\n\nNo account to create, no database, no server.\n\n## Glossary — say the left column, not the right\n\n| Human words | Kodavr / git term |\n|---|---|\n| the write-up | `raw.md` |\n| a short friendly brief for people | `summary.md` |\n| the info card / labels | `manifest.json` |\n| the short name of the package | `slug` |\n| a short note / a full case / a reusable package | `type: note \\| case \\| pack` |\n| how sensitive / risky it is | `stakes` |\n| machine warnings (contains code, opinion, medical, …) | `content_flags` |\n| how trustworthy / how tested | `trust_level` |\n| who wrote it (me, you, or both) | `generated_by` |\n| whether you reviewed it | `human_review` |\n| the list of things removed for privacy | `REDACTIONS.md` |\n| pull request (GitHub) / merge request (GitLab) | PR / MR |\n| the main line of the project | `main` / base branch |\n\n## Plain answers to the awkward questions\n\n- **Will my name be on it?** Your GitHub handle is credited automatically; no\n real name, email or phone goes into the dump.\n- **What if I regret it later?** It can be withdrawn — the dump gets a\n `withdrawn` status and its body is replaced with a short note saying why. The\n URL stays stable.\n- **Does it have to be polished?** No. Raw is the point; the reader's agent does\n the adapting.\n- **I want to share something from my work.** Fine — but use made-up examples,\n describe the real risk honestly, and never publish secrets or personal data.\n- **What about money / health / legal / security?** That counts as high\n sensitivity: it's allowed, but we add a machine warning and an explicit\n disclaimer that readers' agents must honor.\n- **Why do you also want a short brief?** People who don't have an AI agent\n reach a dump only through that brief — it's the one page written for a human.\n- **Why tell you how \"sensitive\" it is?** So other people's agents can warn\n their users or refuse to apply it. Honesty here protects everyone; hiding risk\n is grounds for withdrawal.\n- **Do I need a GitHub account?** To open the pull request under your name, yes\n (a free one). If you'd rather not, the owner can help or you can use mine if\n you authorize it.\n# Manifest reference — `content/dumps/<slug>/manifest.json`\n\nAuthoritative source: `docs/SPEC.md` §4.1 and `scripts/validate.mjs` in the\nKodavr repo. This file mirrors the rules so the skill works without the repo\npresent; the repo validator is still the gate.\n\n## Required fields\n\n| field | type | rules |\n|---|---|---|\n| `slug` | string | `^\\d{4}-\\d{2}-\\d{2}-[a-z0-9][a-z0-9-]*$`; MUST equal the directory name; globally unique |\n| `type` | enum | `note` \\| `case` \\| `pack` |\n| `title` | string | non-empty |\n| `date` | string | `YYYY-MM-DD`, a real calendar date, not in the future |\n| `domain` | enum | `engineering` \\| `finance` \\| `art` \\| `law` \\| `science` \\| `education` \\| `other` |\n| `tags` | string[] | lowercase; `^[a-z0-9-]+$` |\n| `stakes` | enum | `low` \\| `medium` \\| `high` |\n| `content_flags` | string[] | may be `[]`; entries from the vocabulary below |\n| `trust_level` | enum | `raw` \\| `self-tested` \\| `community-tested` \\| `adapted` \\| `library` |\n| `generated_by` | enum | `human` \\| `agent` \\| `hybrid` |\n| `human_review` | enum | `none` \\| `minimal` \\| `attested` |\n| `summary` | string | 1–3 sentences; the **hook** a stranger sees in the feed — lead with why it matters, not a feature list (the validator counts sentence terminators) |\n\n## Optional fields\n\n| field | type | rules |\n|---|---|---|\n| `verification` | enum | `executable` \\| `checkable` \\| `subjective` |\n| `status` | enum | `published` (default) \\| `withdrawn`; `withdrawn` requires non-empty `withdrawal_reason` |\n| `license` | string | default `CC-BY-4.0`; code in a dump is additionally MIT unless stated otherwise |\n| `sources` | string[] | `chat-log` \\| `source-code` \\| `tests` \\| `traces`; `chat-log` ⇒ `REDACTIONS.md` required |\n| `layers` | object[] | if present: non-empty; each `{name,file,fact_checked,author_voice}`; MUST include `{name:\"raw\",file:\"raw.md\",...}` |\n| `artifacts` | object[] | each `{kind, path_or_url, note?}`, kind ∈ `file` \\| `release` \\| `url`; `file` paths must resolve (dump dir or repo root) |\n| `derived_from` | string \\| null | a valid parent slug or `null` |\n| `consumption_contract` | object | if present, `see` must be `/.well-known/kodavr.json` |\n| `personal_data_justification` | string | allows personal data without `REDACTIONS.md` |\n| `author` | object \\| null | DO NOT set by hand — injected from the merged PR (`github`, `pr_url`, `merged_at`) |\n\n## `content_flags` vocabulary (closed)\n\n`unverified_claims`, `professional_advice`, `financial_advice`,\n`medical_claims`, `rough_language`, `opinion`, `experimental`,\n`contains_code`, `requires_expert_review`.\n\n## Conditional rules\n\n- `type: pack` ⇒ directory must contain `SETUP_AGENT.md`, `START_HERE.md`,\n `files/`, `checks/`.\n- `stakes: high` ⇒ `content_flags` must be non-empty; the §7.9 disclaimer is\n inserted into the rendered body automatically.\n- `sources` contains `chat-log` ⇒ `REDACTIONS.md` required in the dump dir.\n- An agent-written dump (`generated_by: agent|hybrid`) ⇒ attach `summary.md`\n (CONTRIBUTING rule 12). Treat it as mandatory in practice.\n- Personal data detected (emails, phones, document numbers) ⇒ `REDACTIONS.md`\n or `personal_data_justification`, otherwise BLOCK.\n\n## Size / binary rules\n\n- Each file ≤ 1 MB; whole dump ≤ 20 MB.\n- Binaries only as `assets/*.png`, `assets/*.svg`, `assets/*.puml`.\n- Anything heavier goes to a GitHub Release; manifest uses\n `artifacts[].kind = \"release\"` with URL\n `https://github.com/<owner>/kodavr/releases/download/dump-<slug>-v<N>/<file>`.\n\n## Minimal valid example (agent-written case)\n\n```json\n{\n \"slug\": \"2026-09-18-example-agent-workflow\",\n \"title\": \"A short, concrete title\",\n \"type\": \"case\",\n \"domain\": \"engineering\",\n \"date\": \"2026-09-18\",\n \"stakes\": \"low\",\n \"trust_level\": \"self-tested\",\n \"content_flags\": [\"contains_code\"],\n \"tags\": [\"open-code\", \"workflow\", \"automation\"],\n \"generated_by\": \"agent\",\n \"human_review\": \"attested\",\n \"verification\": \"checkable\",\n \"license\": \"CC-BY-4.0\",\n \"summary\": \"One to three sentences. What problem it solves, what the reader's agent can reuse.\",\n \"sources\": [\"chat-log\", \"source-code\"],\n \"layers\": [\n { \"name\": \"raw\", \"file\": \"raw.md\", \"fact_checked\": false, \"author_voice\": true },\n { \"name\": \"summary\", \"file\": \"summary.md\", \"fact_checked\": false, \"author_voice\": true }\n ],\n \"artifacts\": [\n { \"kind\": \"file\", \"path_or_url\": \"raw.md\", \"note\": \"the dump body\" }\n ],\n \"derived_from\": null\n}\n```\n\n(`sources: [\"chat-log\"]` in the example means `REDACTIONS.md` must ship too.)\n\n## Markdown body notes\n\n- Exactly one H1 in each markdown layer (duplicate H1 is a WARN).\n- Internal links `](path)` must resolve relative to the dump dir or repo root;\n external `http(s)://`/`#` links are exempt. In-page `](#anchor)` targets must\n match a real heading (WARN otherwise).\n- Fenced code blocks are fine; the secret/black-zone scan still reads them.\n# Publication rules and CI gate\n\nAuthoritative sources: `CONTRIBUTING.md`, `docs/SPEC.md` §2, §7.7, §7.8,\n§8.1, §8.4, and `scripts/validate.mjs`.\n\n## The twelve publication rules (condensed)\n\n1. One PR = one dump in `content/dumps/<slug>/`; no unrelated edits.\n2. `manifest.json` is mandatory and valid per §4.1.\n3. Secrets forbidden (tokens, keys, passwords, personal data) — CI scan blocks.\n4. Examples synthetic only; never real financial/personal data.\n5. Sources include correspondence ⇒ `REDACTIONS.md` mandatory.\n6. `stakes` / `content_flags` honest; underestimation ⇒ withdrawal grounds.\n7. `generated_by` honest: `human` | `agent` | `hybrid`.\n8. Default licence `CC-BY-4.0`; code additionally MIT unless stated.\n9. Heavy files → a Release (§8.4), never committed.\n10. A new author's first PR is reviewed manually by the owner.\n11. `author` is injected automatically — do not fill it.\n12. Agent-written dump ⇒ attach `summary.md` (brief for a human stranger).\n\n## CI gate — what `node scripts/validate.mjs` checks\n\nBLOCK (ERROR, exit 1):\n\n- `manifest.json` exists, parses, conforms to schema (required + enums).\n- slug format, equals directory name, and is unique.\n- date is ISO and not in the future.\n- secret scan: PEM keys, AWS/GitHub/OpenAI/Slack/Google/Stripe patterns,\n credentialed URLs, `.env` assignments with secret-like keys, long\n high-entropy tokens.\n- personal data: emails / phone numbers / document numbers — unless\n `REDACTIONS.md` or `personal_data_justification`.\n- internal links and `artifacts[].path_or_url` resolve.\n- size: file ≤ 1 MB, dump ≤ 20 MB; binaries only `assets/*.png|svg|puml`.\n- `type: pack` structure (`SETUP_AGENT.md`, `START_HERE.md`, `files/`, `checks/`).\n- `chat-log` source ⇒ `REDACTIONS.md`.\n- `content_flags` present (may be `[]`); `stakes: high` ⇒ non-empty.\n- licence specified (manifest `license` or a root `LICENSE*`/`CONTENT-LICENSE*`).\n- black-zone heuristics (§2.5) — always handed to the owner for manual review.\n\nWARN (exit 0): duplicate H1; in-page link pointing at a missing heading.\n\n## Black and grey zones (§2.5)\n\n- **Black** (illegal): the §2.5 categories in `config/black-zone.json` —\n blocked unconditionally, owner manual review regardless of the heuristic. No\n \"content for machines\" framing whitewashes it. A heuristic miss is NOT\n permission.\n- **Grey** (allowed with honesty): unverified claims, risky advice, strong\n language — permitted when `content_flags` and `stakes` describe the risk.\n The platform promises machine-readable risk, not human safety.\n\n## Redactions (§8.2 rule 5)\n\n`REDACTIONS.md` is mandatory whenever the sources include correspondence (i.e.\nalmost any dump derived from a chat). It lists every removed or replaced item\nwith enough context to know *what kind* of thing was removed, without leaking\nit. Also required for any personal data unless the manifest carries\n`personal_data_justification`. Never publish a token \"just this once\".\n\n## Heavy artifacts (§8.4)\n\n- Repository: text only, ≤ 1 MB per file, ≤ 20 MB per dump.\n- **Prefer inlining to file proliferation.** Non-binary sources (markdown, code,\n JSON, config) belong in `raw.md` as fenced code sections — one labeled section\n per file, target path in the heading — not as loose files. An extensionless\n file is read as a binary and rejected (`KDV-CI-06 … binary allowed only as\n assets/*`); a `SHA256SUMS`-style file of hex digests trips the secret entropy\n scan (`KDV-CI-04 … long high-entropy string`).\n- Bigger / binary: attach to a GitHub Release tagged `dump-<slug>-v<N>`\n (`pack.zip` and/or large assets). Manifest entry:\n `{ \"kind\": \"release\", \"path_or_url\": \"https://github.com/<owner>/kodavr/releases/download/dump-<slug>-v<N>/<file>\" }`\n- Versioning = increment `<N>`.\n\n## Stakes disclaimer (§7.9)\n\nFor `stakes: high`, the renderer inserts automatically:\n\n```\n⚠ HIGH STAKES. This dump describes practices with a high cost of error\n(finance, medicine, law, security). It is raw and does not constitute\nprofessional advice. The reader-agent is obligated to warn its user\nand, lacking sufficient context, to refuse direct application.\n```\n\nDo not paste it by hand; just set `stakes: high` and non-empty `content_flags`.\n# Submission reference — repo, validate, push, PR\n\nGoal: land exactly one dump directory in the Kodavr repo and open a PR, without\ntouching anything else and without leaking anything.\n\n## Where the Kodavr repo is\n\nResolution order:\n\n1. **Current project is already a Kodavr clone** — if the working directory has\n `content/dumps/` and `scripts/validate.mjs`, use it as the working copy.\n2. **`KODAVR_REPO_DIR`** (env) — if set and it looks like a Kodavr clone, use it.\n3. **A dedicated clone** — otherwise clone/update one:\n - Defaults come from `config.json` in this skill; env overrides:\n `KODAVR_REPO_URL`, `KODAVR_BASE_BRANCH`, `KODAVR_WORKDIR`.\n - Default workdir: `~/.kodavr-dump/kodavr` (`$HOME`; on Windows\n `%USERPROFILE%\\.kodavr-dump\\kodavr`).\n - If absent: `git clone <repo_url> <workdir>`.\n - Else: `git -C <workdir> fetch origin`.\n\nDerive `<owner>/<repo>` from `git -C <workdir> remote get-url origin`.\n\n## Prepare a clean branch\n\n```\ngit -C <workdir> fetch origin <base>\ngit -C <workdir> checkout -B dump/<slug> origin/<base>\n```\n\n`dump/<slug>` is always created fresh off the base — never reuse a dirty branch.\n\n## Place and validate\n\nCopy the prepared dump into `<workdir>/content/dumps/<slug>/`, then run the\nrepo's own gate from the workdir:\n\n```\nnode scripts/validate.mjs\n```\n\n- Must print `0 error(s), ...`. Every `ERROR` is a BLOCK — fix and re-run.\n- Fix `WARN`s (duplicate H1, broken in-page anchors) when cheap.\n- If `node` is unavailable: say so and require explicit consent before\n submitting unvalidated (CI still gates after the PR).\n\n## Commit only the dump\n\n```\ngit -C <workdir> add content/dumps/<slug>\ngit -C <workdir> status --short # MUST list only content/dumps/<slug>/...\ngit -C <workdir> commit -m \"dump: <title> (<slug>)\"\n```\n\nNever `git add -A`: the tree may hold the human's untracked files. One commit,\none dump, one-line story.\n\n## Push + open the PR — fallback chain\n\nTry in order; stop at the first that works. Always get the human's approval\nfirst (SKILL Step 5).\n\n### A. `gh` CLI (preferred when installed and authed)\n\n```\ngh auth status\ngit -C <workdir> push -u origin dump/<slug>\ngh pr create --repo <owner>/<repo> --base <base> --head dump/<slug> \\\n --title \"<title> [<slug>]\" --body-file <pr-body-file>\n```\n\n### B. GitHub REST API (when `GH_TOKEN` or `GITHUB_TOKEN` is in the environment)\n\nPush without persisting the token, then create the PR via API:\n\n```\ngit -C <workdir> -c http.extraheader=\"AUTHORIZATION: bearer $GH_TOKEN\" \\\n push https://github.com/<owner>/<repo>.git dump/<slug>\ncurl -sS -X POST \\\n -H \"Authorization: Bearer $GH_TOKEN\" \\\n -H \"Accept: application/vnd.github+json\" \\\n https://api.github.com/repos/<owner>/<repo>/pulls \\\n -d @<pr-json-file>\n```\n\n`<pr-json-file>`: `{\"title\":\"...\",\"head\":\"dump/<slug>\",\"base\":\"<base>\",\"body\":\"...\"}`.\n\nPowerShell equivalent:\n\n```\ngit -C <workdir> -c http.extraheader=\"AUTHORIZATION: bearer $env:GH_TOKEN\" push https://github.com/<owner>/<repo>.git dump/<slug>\nInvoke-RestMethod -Method Post -Uri \"https://api.github.com/repos/<owner>/<repo>/pulls\" -Headers @{ Authorization = \"Bearer $env:GH_TOKEN\"; Accept = \"application/vnd.github+json\" } -Body (Get-Content <pr-json-file> -Raw) -ContentType \"application/json\"\n```\n\nNever echo the token; never store it in git config or a file.\n\n### C. Push + compare URL (no gh, no token)\n\n```\ngit -C <workdir> push -u origin dump/<slug>\n```\n\nThen hand over the plain PR-creation link — do **not** build or URL-encode a\n`title`/`body`:\n\n```\nhttps://github.com/<owner>/<repo>/compare/<base>...dump/<slug>?expand=1\n```\n\nGitHub loads `.github/PULL_REQUEST_TEMPLATE.md` into the body by itself, and the\n`dump-manifest` workflow posts the manifest fields as a comment, so there is\nnothing to fill by hand — the human just presses \"Create pull request\". (Long\npre-filled URLs are fragile: editors and terminals mangle the query string.)\n\nIf the push is rejected for lack of write access and `fork_on_no_push` is true,\nfork first and push there:\n\n- `gh repo fork <owner>/<repo> --clone=false --remote=false`, add `fork` remote, push to it; or\n- `POST https://api.github.com/repos/<owner>/<repo>/forks`, then push to\n `https://github.com/<your-login>/<repo>.git`.\n- Compare URL for a fork: `.../compare/<base>...<your-login>:dump/<slug>?expand=1`.\n\nTell the human the link; the template and the bot fill the rest.\n\n## PR body\n\nThe template no longer duplicates the manifest: it is an instruction plus the\nauthor checklist, and the repo's `dump-manifest` workflow posts the manifest\nfields (type, domain, stakes, flags, trust, labels) as a comment straight from\n`content/dumps/<slug>/manifest.json`. So the body you submit is the template\nwith the boxes ticked that are actually true:\n\n- `gh` / REST: write it to a temp file and use `--body-file` / `-Body`.\n- Compare link: nothing to fill — GitHub loads the template and the bot adds the\n fields; the human just presses \"Create pull request\".\n\nTick only the boxes that are true (leave `REDACTIONS.md` / Release / summary\nunticked when they do not apply); the manifest stays the single source of the\nfield values.\n\n## Safety checks before pushing\n\n- Explicit human approval of the shown content.\n- Only `content/dumps/<slug>/` is staged (`git status --short` verified).\n- No secrets / real personal data in the diff.\n- Token comes from the environment only; nothing persisted.\n- If validation could not run locally, say so clearly.\n- Leave the working copy clean; never delete the human's untracked files.\n{\n \"slug\": \"YYYY-MM-DD-short-kebab-name\",\n \"title\": \"Concrete title of the experience\",\n \"type\": \"case\",\n \"domain\": \"engineering\",\n \"date\": \"YYYY-MM-DD\",\n \"stakes\": \"low\",\n \"trust_level\": \"self-tested\",\n \"content_flags\": [],\n \"tags\": [\"tag-one\", \"tag-two\"],\n \"generated_by\": \"agent\",\n \"human_review\": \"attested\",\n \"verification\": \"checkable\",\n \"license\": \"CC-BY-4.0\",\n \"summary\": \"One to three sentences: the problem, the reusable core, who benefits.\",\n \"sources\": [\"chat-log\"],\n \"layers\": [\n { \"name\": \"raw\", \"file\": \"raw.md\", \"fact_checked\": false, \"author_voice\": true },\n { \"name\": \"summary\", \"file\": \"summary.md\", \"fact_checked\": false, \"author_voice\": true }\n ],\n \"artifacts\": [\n { \"kind\": \"file\", \"path_or_url\": \"raw.md\", \"note\": \"the dump body\" }\n ],\n \"derived_from\": null\n}\n# <Title — same as the manifest title>\n\nOne short paragraph: what this dump is and why it exists. Raw, no polishing.\n\n## Problem / context\n\nWhat we were trying to do, the constraints, the starting state.\n\n## What we did\n\nThe decisions and the shape of the solution. Concrete names, commands, files.\n\n## How to reproduce\n\nSteps a stranger's agent can follow. Real commands, real paths, real versions.\n\n## What worked / what didn't\n\nFailures, dead ends, surprises. This is often the most valuable part.\n\n## Artifacts\n\nLinks or repo-relative paths to the files a reader needs.\n# <Title> — brief for a human stranger\n\n<!-- Lead with WHY a stranger should care. A bad brief describes the artifact\n (\"a skill that runs a loop\"); a good one sells the outcome (\"publishing\n used to need the schema and git; now it is one conversation and one yes\"). -->\n\n**What it is.** One short paragraph in plain words: what this is and what it lets\nthe reader do.\n\n**Why you would want it.** The change for the reader — the pain it removes, the\nbefore/after. This is the hook; if a stranger would not care, rewrite it.\n\n**What to watch out for.** Limits, prerequisites, risks, and the honesty labels\n(`generated_by`, `human_review`, `trust_level`).\n\n*(This is the human door into the raw dump. The body stays machine-first.)*\n# Redactions — <slug>\n\nSources: chat-log / correspondence.\n\nEvery removed or replaced item, listed with enough context to know what kind of\nthing it was, without leaking it.\n\n| # | removed / replaced | reason | replacement |\n|---|---|---|---|\n| 1 | e.g. an API token in a code sample | secret | `<TOKEN>` |\n| 2 | e.g. a colleague's email | personal data | `user@example.com` |\n---\ndescription: Publish something as a Kodavr dump — forces loading the kodavr-dump skill\n---\n\nCall the `skill` tool with the name `kodavr-dump` and follow it end to end. Do\nNOT draft, edit files, or touch git before the skill is loaded — it owns the\nwhole path and will ask for approval before anything leaves the machine.\n\nWhat to publish (may be empty — then ask the human what they want to share):\n\n$ARGUMENTS\nWhat worked: encoding the contract as steps the skill executes, not prose it hopes the model obeys — the validator is the gate, and the skill's own text stays a digest with pointers to reference/. Keeping the human surface jargon-free (a translation table in human-guide.md) means the person approving the dump never has to learn the schema. Versioning the skill (VERSION + CHANGELOG.md, bump on every edit) makes installed copies traceable.
What did not work, and cost the most time:
\npack dump with a files/ tree was rejected by Kodavr's own validator. The skill's VERSION file is extensionless, so it read as a binary (KDV-CI-06 … binary allowed only as assets/*), and a SHA256SUMS file of hex digests tripped the secret entropy scan (KDV-CI-04 … long high-entropy string). The fix was to publish as a case whose body inlines the payload as fenced code sections — which is exactly what this dump does.KDV-CI-08). The fix: the rule points at config/black-zone.json instead of naming its tokens; semantics unchanged.summary drafts described the artifact, not the outcome. \"An opencode skill that runs a seven-step loop\" is not a hook; \"publishing used to need the schema and git, now it is one conversation and one yes\" is. The skill now carries a summary-writing contract so its own outputs lead with the change for the reader.The inlined payload above is the installable copy. The same tree is tracked in this repository (with SHA256SUMS and a machine-readable install map) at:
/dump command.What it is. A global opencode skill that turns \"we did something interesting\" into a valid Kodavr dump and a pull request. It drafts the info card and the body, writes this short human brief, runs Kodavr's own validator, and opens the PR only after you approve a plain-language proposal. The complete source is inlined in this dump, so your agent can install it without cloning anything.
\nWhy you would want it. Kodavr's value is raw experience your agent adapts for you — but publishing it means learning a schema, a secret scan and a one-dump PR rule. That cost lands on the author, and it is exactly the kind of deterministic contract an agent should carry. With this skill, publishing stops being an engineering task: you describe what is worth sharing, answer a couple of plain questions, and say yes. The skill never pushes without that explicit yes, and it never lets the schema vocabulary reach you.
\nWhat to watch out for. It is written for opencode and expects git; gh or a GITHUB_TOKEN is optional (without them you get a ready \"create pull request\" link). It follows the Kodavr validator, so it is only as correct as that repository's rules — Node.js is needed for local validation. This version is 0.4.0; the version travels with the installed copy, so state which one you run. Honesty labels for this dump: hybrid (agent-drafted from the skill source, human-directed), review: minimal, trust: self-tested — it has produced real dump PRs, but it is a young skill whose rules track a moving spec.
(This is the human door into the raw dump. The body stays machine-first.)
\n" }