@1aboveio/skills 1.0.14 → 1.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1aboveio/skills",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "description": "Every 1aboveio skill package in one: install once, then choose which packages Pi loads with npx @1aboveio/skills select.",
   "license": "MIT",
   "repository": {
@@ -28,8 +28,8 @@
   "nativeCodex": {
     "schemaVersion": 1,
     "metadataPath": ".codex-plugin/resources.json",
-    "metadataDigest": "5a89642fb1549c82420cbba78a75eaff01509d14cbf556480130a688e7ca1efe",
-    "releaseIdentity": "1d0affb17cf284c052ad00266f7d5ea31a7f7f9bb7f8ae6435b200835710e123"
+    "metadataDigest": "2bdb58dba1de073baf79efe2c5118ad75c996710344a3cde581976921c1b23ec",
+    "releaseIdentity": "a8975fa459ebba2a3e2661d861bdb9d43c072c1b01adaf41def9a93523782800"
   },
   "pi": {
     "skills": [
@@ -260,7 +260,7 @@
         ]
       }
     ],
-    "digest": "ffe17fe4c3bfd5076e842358a22f58b116f060bd779f788f4ba3fd7b814f8b0e"
+    "digest": "6ad0dafe4a400162776b1bf6d7c9e5ab31bf37a86d18b035fcadc4c11d06f799"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skills/app-dev/airflow/SKILL.md

@@ -2,7 +2,7 @@
 name: airflow
 description: Airflow DAG architecture and conventions. Use when designing, writing, reviewing, testing, or debugging Airflow DAGs and tasks, including TaskGroups, data intervals, timezone-aware date parameters, CLI validation, environment-based scheduling, and pytest integrity tests.
 user-invocable: true
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Airflow DAG Development Patterns

package/skills/app-dev/android-development/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: android-development
 description: "Prove and debug Expo / React Native apps on an owned Android emulator. Use for Android startup/rendering failures, Metro or ADB problems, UiAutomator/harness failures, APK builds, SDK/NDK/JDK workspace setup, native journey validation, and choosing Kotlin/Compose versus React Native for Android flows. Reproduce failed Android CI checkpoints off CI before fixing and redispatching. Standalone invocation offers Project or Session; init persists repo conventions. NOT for workflow YAML, CI speed or runners (github-actions), browser tests (e2e-test), iOS (ios-foundation), plain Jest tests, or signing/store release."
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Android development
@@ -18,7 +18,8 @@ Project rules and required CI remain binding; this skill does not add acceptance
   leaves files unchanged. Do not offer global persistence.
 - **Project**, `/android-development init`, or an explicit request to save repo conventions:
   follow [initialization](references/init.md). Preview, then apply the authorized missing
-  `CONTRIBUTING.md` section and `AGENTS.md` pointer. No second approval is needed unless
+  `CONTRIBUTING.md` section and `AGENTS.md` task-entry loader and guide pointer. Check
+  the skill loader separately from an existing guide link. No second approval is needed unless
   existing policy conflicts. Initialization is not a policy refresh or delivery permission.
 - **Session:** apply this workflow without writing guidance or agent settings. Retain the
   choice through reload/compaction in this session; a new session makes its own choice.

package/skills/app-dev/android-development/references/diagnosis.md

@@ -103,6 +103,11 @@ worker's "running" status does not impose a timeout or demonstrate progress. The
 whole journey. Set a positive value for unattended runs; its backward-compatible
 zero default disables that deadline. Allow time for the owner to finish cleanup.
 
+Use the harness's background-task mechanism when a journey can exceed the foreground
+command limit. Budget for the selected journey and owned cleanup; feedback-time targets
+are not kill deadlines. Continue independent work and inspect the terminal result when
+notified, rather than waiting or polling in the foreground. Do not add another watcher.
+
 For a hung test, identify the actual outstanding command and last completed assertion.
 If the test waits for a child to exit, check whether its input actually requires exit.
 Reduce that question to a bounded host test before launching another emulator.

package/skills/app-dev/android-development/references/feature-work.md

@@ -30,6 +30,21 @@ Native/build-input changes invalidate that reuse; unknown compatibility calls fo
 rebuild, not an assertion that the old APK is current. Do not run `expo prebuild` routinely
 against tracked native projects.
 
+### Check journey admission before reserving devices
+
+Before an expensive native journey, verify the exact selected case and supported arguments
+against the existing runner, required installation/resource owners, effective test flags,
+and device settings. Use existing help, parser tests or preflight commands when available;
+do not invent a selector or build another preflight framework. Missing admission support
+is a harness limitation to resolve, not a reason to allocate devices and discover it later.
+Continue independent source tests while device prerequisites are checked.
+
+Apply lifecycle-changing display size, density and other required presentation settings
+before app launch when the journey relies on retaining that Activity or observation scope.
+Read back the effective settings through the existing owner. A later setting change may
+recreate the Activity; do not hide scope retirement with registration retries or relaxed
+identity checks. Keep this check scoped to the selected case, not every possible device cell.
+
 ### Verify command expansion
 
 Before adopting a native fast path, trace its package script, wrapper, Gradle tasks and

package/skills/app-dev/android-development/references/init.md

@@ -14,8 +14,9 @@ node {baseDir}/scripts/init.mjs [--repo-root <dir>] [--write]
 - `--write` applies the plan. `--repo-root` selects the project; without it the nearest Git root
   from the current directory is used, falling back to the current directory when there is none.
 - `--help` prints the usage line.
-- An unknown argument, an unresolvable root, a malformed marker or an unsafe target exits
-  non-zero with a message and no writes.
+- An unknown argument, an unresolvable root, a malformed marker, an unsafe target or a file that
+  ends inside an unclosed fenced code block or HTML comment exits non-zero with a message and no
+  writes, in preview and with `--write` alike.
 
 ## Files and ownership
 
@@ -27,19 +28,35 @@ to a newly created Android section; report unresolved commands instead of guessi
 | File | Write |
 | --- | --- |
 | `CONTRIBUTING.md` | The `## Android development` section, wrapped in `<!-- conventions:android:start -->` / `<!-- conventions:android:end -->`, with `references/android-conventions.md` as its body. |
-| `AGENTS.md` | A short pointer to the selected `CONTRIBUTING.md`, added only when no correct loader link exists yet. |
+| `AGENTS.md` | An `Android task entry` skill-loading block between `conventions:android-task-entry` markers, plus a pointer to the selected `CONTRIBUTING.md` when missing. Check these independently: a contributor-guide link alone is not a skill loader. |
 
 Each file is created only when it is absent. The helper never edits `CLAUDE.md`, never writes into
 a parent project, a home directory or global agent configuration, and never reaches outside the
 selected root.
 
 After applying authorized additions, verify that each existing supported agent entrypoint
-reaches the Android section, directly or through its instruction chain. The helper configures
+reaches both the skill task-entry instruction and the Android contributor-guide section,
+directly or through its instruction chain. A direct link to `CONTRIBUTING.md` does not
+establish that the entrypoint loads the skill rule in `AGENTS.md`. The helper configures
 `AGENTS.md`; it does not certify an independent `CLAUDE.md` loader. Preserve existing chains
 and do not edit that entrypoint under this init permission. If one does not reach the guide,
 report the files configured and the unresolved loading path as partial setup. Obtain separate
 authorization for any additional loader edit instead of silently claiming complete setup.
 
+The task-entry block requires reading and applying the installed `android-development`
+skill before Android-specific commands, during issue-unit preflight, in delegated Android
+workers, and again after compaction when its rules are lost. Keep commands and validation
+policy in `CONTRIBUTING.md`, not this loader. An existing direct read/load-before rule or
+managed block is preserved. A managed block is preserved only while it still holds an active
+loader: an empty block, or one whose only loader is commented out or written as a code example,
+is refused rather than counted as configured. A direct `do not load`-style rule that conflicts
+with the loader is refused too, wherever it sits in the file. Fenced code, indented code, HTML
+comments and inline code are documentation, so an example never counts as an active loader or as
+a conflict. An unrecognized `Android task entry` section requires manual reconciliation rather
+than a competing block. Inspect existing rules for conflicts before applying the helper; it
+cannot interpret every natural-language policy. This missing-loader addition is part of explicit
+init even in previously initialized repos, not an automatic update.
+
 ## Resolve the repo command map
 
 The initializer, not the deterministic writer, inspects existing scripts and guidance.
@@ -81,6 +98,11 @@ Existing guidance wins over the template:
 - Refuse a mutation of a multiply hard-linked file or of an alias to the protected
   `CLAUDE.md` entrypoint. This includes a shared AGENTS/CLAUDE target: preserve it and
   report the boundary rather than silently granting a new write permission.
+- Refuse an addition to a file that ends inside an unclosed fenced code block or HTML comment.
+  Appended guidance would land inside that construct, be inactive, and be appended again on
+  every run. The helper never closes it for you: preserve the manual text, repair the fence or
+  comment, and rerun. A file that needs no addition is reported unchanged, so an
+  already-configured project behind such a construct is not blocked.
 - An existing pointer is reused only when its link resolves to the selected `CONTRIBUTING.md`,
   and a new pointer is written relative to the real location of `AGENTS.md`. A link to some other
   file, such as a nested package guide, does not count as this project's loader.

package/skills/app-dev/android-development/scripts/init.mjs

@@ -7,6 +7,14 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 
 const sectionTitle = 'Android development'
 const sectionId = 'android'
+const taskEntryTitle = 'Android task entry'
+const taskEntryBody = `## ${taskEntryTitle}
+
+For Android implementation, runtime debugging, native builds, or device validation,
+read and apply the installed \`android-development\` skill before choosing
+Android-specific commands. In issue workflows, load it during unit preflight.
+Delegated Android workers must load it too. After compaction, reload it if its
+instructions are no longer in context.`
 const usage = 'node init.mjs [--repo-root <dir>] [--write]'
 
 function parseArgs(argv) {
@@ -174,7 +182,7 @@ function stripHtmlComments(line, depth = 0) {
 
 // Markdown-aware view: inactive lines are fenced code, indented code or HTML comments.
 // Inline code and HTML comments are blanked from active text so examples never count.
-function markdownView(current) {
+function scanMarkdown(current) {
   const lines = []
   let fence = null
   let commentDepth = 0
@@ -217,10 +225,63 @@ function markdownView(current) {
     previousBlank = blank
     lines.push({ raw: line, text: active ? text : '', active, comments })
   }
-  return lines
+  // An open fence or comment at the end of the file would swallow anything appended after it.
+  return { lines, fence, commentDepth }
+}
+
+function markdownView(current) {
+  return scanMarkdown(current).lines
+}
+
+// End of the paragraph starting at `start`; a span never pairs across a blank line.
+function paragraphEnd(text, start) {
+  const blank = /\n[ \t]*\n/g
+  blank.lastIndex = start
+  const match = blank.exec(text)
+  return match ? match.index : text.length
+}
+
+// Marks inline code spans so a documented example is never read as a project rule.
+// Runs of equal length pair up inside one paragraph; an unmatched run is literal text, so it
+// never consumes a later rule. The rule text itself stays readable, only its span is marked.
+function inlineCodeMask(text) {
+  const mask = new Uint8Array(text.length)
+  const runs = [...text.matchAll(/`+/g)]
+  let index = 0
+  while (index < runs.length) {
+    const opening = runs[index]
+    const limit = paragraphEnd(text, opening.index)
+    let closing = index + 1
+    while (closing < runs.length && runs[closing].index < limit
+      && runs[closing][0].length !== opening[0].length) closing++
+    if (closing === runs.length || runs[closing].index >= limit) {
+      index += 1
+      continue
+    }
+    mask.fill(1, opening.index, runs[closing].index + runs[closing][0].length)
+    index = closing + 1
+  }
+  return mask
 }
 
-function append(current, body) {
+// Only a match that starts outside inline code is an instruction rather than an example.
+// The rule itself keeps its text, because the skill name is normally written as code.
+function matchesOutsideInlineCode(text, pattern) {
+  const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`
+  const global = new RegExp(pattern.source, flags)
+  const mask = inlineCodeMask(text)
+  for (const match of text.matchAll(global)) {
+    if (!mask[match.index]) return true
+  }
+  return false
+}
+
+function append(current, body, name) {
+  const { fence, commentDepth } = scanMarkdown(current)
+  if (fence || commentDepth) {
+    const construct = fence ? 'an unclosed fenced code block' : 'an unclosed HTML comment'
+    throw new Error(`${name} ends inside ${construct}; appended Android guidance would be inactive and appended again on every run. Close it and rerun init; nothing was changed`)
+  }
   const separator = current.endsWith('\n\n') ? '' : current.endsWith('\n') ? '\n' : '\n\n'
   return `${current}${separator}${body.trim()}\n`
 }
@@ -258,7 +319,7 @@ function countMarkers(lines, start, end) {
   return { starts, ends }
 }
 
-function preserveOrAdd(current, title, id, body) {
+function preserveOrAdd(current, name, title, id, body) {
   const start = `<!-- conventions:${id}:start -->`
   const end = `<!-- conventions:${id}:end -->`
   const { starts, ends } = countMarkers(markdownView(current), start, end)
@@ -266,7 +327,7 @@ function preserveOrAdd(current, title, id, body) {
     throw new Error(`malformed ${title} section markers; preserve and repair existing guidance first`)
   }
   if (starts.length || hasHeading(current, title)) return current
-  return append(current, `${start}\n${body}\n${end}`)
+  return append(current, `${start}\n${body}\n${end}`, name)
 }
 
 function linkFrom(from, to) {
@@ -295,6 +356,42 @@ function hasLoader(current, from, to) {
   return false
 }
 
+function addTaskEntry(current, name) {
+  const start = '<!-- conventions:android-task-entry:start -->'
+  const end = '<!-- conventions:android-task-entry:end -->'
+  const lines = markdownView(current)
+  const { starts, ends } = countMarkers(lines, start, end)
+  if (starts.length !== ends.length || starts.length > 1 || (starts.length && starts[0] > ends[0])) {
+    throw new Error('malformed Android task entry markers; preserve and repair existing guidance first')
+  }
+  // Only active prose can hold a rule: fenced code, indented code, HTML comments, inline code
+  // and fenced examples are documentation. A rule keeps its own inline code, so the skill name
+  // written as `android-development` is still matched by its position outside a code span.
+  const prose = lines.map(line => line.active && line.text.trim()
+    ? stripHtmlComments(line.raw).text : '')
+  const active = prose.join('\n')
+  // Recognize an existing direct loader, not a mere skill mention or guide link.
+  const loader = /^[ \t]*(?:(?:[-+*]|\d+[.)])\s+)?(?:read|load)\s+(?:and\s+apply\s+)?(?:the\s+)?(?:installed\s+)?`?android-development`?\s+skill\s+before\b/im
+  const negation = /\b(?:do not|don't|never|must not)\s+(?:automatically\s+)?(?:read|load|apply|use|follow)\b[^.]{0,120}\bandroid-development\b/i
+  if (matchesOutsideInlineCode(active, negation)) {
+    throw new Error('existing Android skill-loading rule conflicts with task entry; nothing was changed')
+  }
+  if (starts.length) {
+    const from = lines.findIndex(line => line.comments.includes(start))
+    const to = lines.findIndex(line => line.comments.includes(end))
+    const body = prose.slice(from + 1, to).join('\n')
+    if (!matchesOutsideInlineCode(body, loader)) {
+      throw new Error('preserved Android task entry has no active loader; nothing was changed')
+    }
+    return current
+  }
+  if (matchesOutsideInlineCode(active, loader)) return current
+  if (hasHeading(current, taskEntryTitle)) {
+    throw new Error('existing Android task entry needs manual reconciliation; nothing was changed')
+  }
+  return append(current, `${start}\n${taskEntryBody}\n${end}`, name)
+}
+
 function planInitialization(root) {
   const claude = inspectClaude(root)
   const [agents, contributing] = ['AGENTS.md', 'CONTRIBUTING.md'].map(name => resolveTarget(root, name))
@@ -316,13 +413,13 @@ function planInitialization(root) {
   const agentsEntry = readGuidance(agents)
   const contributingEntry = readGuidance(contributing)
 
-  let agentText = agentsEntry.current ?? '# Agent instructions\n'
+  let agentText = addTaskEntry(agentsEntry.current ?? '# Agent instructions\n', agentsEntry.name)
   if (!hasLoader(agentText, agentsEntry, contributingEntry)) {
     const heading = hasHeading(agentText, sectionTitle) ? '' : `## ${sectionTitle}\n\n`
-    agentText = append(agentText, `${heading}Follow [CONTRIBUTING.md](${linkFrom(agentsEntry, contributingEntry)}) for this project's Android validation ladder, device proof and required gates.`)
+    agentText = append(agentText, `${heading}Follow [CONTRIBUTING.md](${linkFrom(agentsEntry, contributingEntry)}) for this project's Android validation ladder, device proof and required gates.`, agentsEntry.name)
   }
 
-  const contributingText = preserveOrAdd(contributingEntry.current ?? '# Contributing\n', sectionTitle, sectionId, sectionBody())
+  const contributingText = preserveOrAdd(contributingEntry.current ?? '# Contributing\n', contributingEntry.name, sectionTitle, sectionId, sectionBody())
 
   const plan = [
     { ...agentsEntry, next: agentText },

package/skills/app-dev/app-debug/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: app-debug
 description: "Diagnose runtime failures in deployed Cloud Run services — 5xx/422 errors, tracebacks, Next.js SSR/hydration or Server Action failures, DB/Secret Manager connection errors, cold-start timeouts, container OOM. NOT for build or deploy failures (cloud-debug)."
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # App Debug

package/skills/app-dev/better-auth/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: better-auth
 description: "Add or debug Better Auth for Next.js App Router: login, sessions, protected routes, middleware, OAuth (including Feishu/Lark), cookies, Prisma, and Auth.js migration."
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Better Auth for Next.js

package/skills/app-dev/data-catalog/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: data-catalog
 description: "Column definitions for warehouse tables, written inside the Spark/PySpark or SQL script that builds each table (CATALOG_TABLE / CATALOG_FIELDS, or a `-- @field` comment block), with a generated markdown catalog in docs/catalog/ and a CI check that fails a PR whose catalog is stale. Use when writing or changing a table script that adds, renames, removes, or changes the meaning of an output column or feature; when asked what a warehouse column or feature means; to set a repo up ('init the data catalog', 'generate the data dictionary', '字段字典', 'add catalog CI'); or to audit existing SQL or Spark scripts for undocumented columns. NOT for implementing or tuning the Spark job itself (pyspark), DAG wiring (airflow), or general workflow YAML (github-actions)."
-release-version: 0.46.0
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Data catalog
@@ -12,23 +12,49 @@ and CI fails a pull request when the pages and the scripts disagree.
 
 ## First use in a repo
 
-In a git repo with no `data-catalog.json`, set the repo up **before** the task you
-were asked to do, whatever it is: an audit, a new column, or a question. Setting up
-puts the engine, the CI check, and the conventions in the repo itself, so agents
-and people without this skill follow them from then on.
+No `data-catalog.json` means the repo is not set up. That is a fact about the repo,
+not permission to write to it, and the `## Data catalog task entry` rule that loaded
+this skill is not one either: an audit, a review, a column question or a table-script
+change is the task, and it is done from the sources the repo already has.
+
+- **Read what exists.** `docs/catalog/<table>.md` when the repo has pages, else the
+  script's `CATALOG_TABLE`/`CATALOG_FIELDS`, else its `-- @table`/`-- @field` block,
+  else the SQL or DataFrame code. A definition in the script answers the question;
+  never hand-write the missing page.
+- **Audit read-only.** `python3 <skill-base-dir>/scripts/data_catalog.py audit
+  'jobs/**/*.py' 'sql/**/*.sql'` needs no config and writes nothing; it exits 2 only
+  with neither a config nor globs.
+- **A check you cannot run stays pending.** `generate`, `generate --check` and `drift`
+  exit 2 without `data-catalog.json`. Report them pending — "the catalog is not set up
+  here" — not "no findings", "green" or "CI passes", and do not run `init --write` to
+  make them runnable: running them is the task, making them runnable is setup.
+- **Offer setup once.** One short line: `init --write` with the `--scripts` globs and
+  `--languages` you would use, plus `persist-conventions.mjs --write` for the
+  conventions section, the `AGENTS.md` pointer and the task-entry rule. Say nothing was
+  written, keep working, once per session per repo. Not an approval checkpoint.
+- **Setting up is an explicit request.** "init the data catalog", "generate the data
+  dictionary", "字段字典", "add catalog CI", "set up the catalog here" — that
+  authorizes these writes in that repo only. An automatic review, the loader rule, a
+  handoff from another skill, or having read this section do not.
+
+With that request, setup is:
 
 1. `python3 <skill-base-dir>/scripts/data_catalog.py audit '<globs>'` to find the
    table scripts; choose `--scripts` globs that cover them and nothing else.
 2. Pick `--languages` from the repo's existing docs (Chinese docs: `zh,en`;
    otherwise `en`). Run `init` with them and `--write` ([Init](#init)).
 3. `node <skill-base-dir>/scripts/persist-conventions.mjs --repo-root <repo> --write`
-   writes the `## Data catalog conventions` section of `CONTRIBUTING.md` and points
-   `AGENTS.md` at it.
+   writes the `## Data catalog conventions` section of `CONTRIBUTING.md`, points
+   `AGENTS.md` at it, and adds the `## Data catalog task entry` rule that loads this
+   skill for column or table-script work. It is the only writer of those files and
+   writes only with its own `--write`; an ordinary catalog task never runs it.
 4. Then do the task. In the reply, list what setup added, and say the Data catalog
    check runs on PRs but is not required.
 
-Skip setup outside a git repo, or when the user says not to change the repo.
-Never document tables during setup unless the task asks for it.
+Outside a git repo there is nothing to set up: say so. Never document tables during
+setup unless the task asks for it. Repeating setup with the same inputs leaves the
+configured files unchanged; report a missing input or a conflicting rule instead of
+claiming success.
 
 ## Find your task
 
@@ -36,7 +62,7 @@ Never document tables during setup unless the task asks for it.
 |---|---|
 | Writing or changing a table script | [While coding](#while-coding), then [references/field-definitions.md](references/field-definitions.md) |
 | "What does column X mean?" | Read `docs/catalog/<table>.md`; with no page, read the script's `CATALOG_FIELDS`, then its SQL |
-| The repo has no `data-catalog.json` | [First use in a repo](#first-use-in-a-repo) |
+| The repo has no `data-catalog.json` | Do the task read-only, then offer setup once ([First use in a repo](#first-use-in-a-repo)) |
 | Find scripts with missing or weak definitions | [Audit](#audit) |
 | Document an existing table | [Backfill one table](#backfill-one-table) |
 | CI says the catalog is stale | `python3 <engine> generate`, commit the pages |
@@ -46,8 +72,8 @@ Never document tables during setup unless the task asks for it.
 
 `<engine>` is `scripts/data-catalog/data_catalog.py` in the repo, or
 `<skill-base-dir>/scripts/data_catalog.py` before the repo has a copy. When
-`python3 <engine> version` differs from the skill's copy, refresh with
-`init --write`.
+`python3 <engine> version` differs from the skill's copy, the refresh is
+`init --write`, which needs a setup request ([First use in a repo](#first-use-in-a-repo)).
 
 ## The files
 
@@ -61,7 +87,7 @@ Never document tables during setup unless the task asks for it.
 | `scripts/data-catalog/data_catalog.py` | engine copied from this skill | never; refresh with init |
 | `.github/workflows/data-catalog.yml` | generated CI check | never; rerun init |
 | `CONTRIBUTING.md` section between `conventions:data-catalog` markers | the conventions, for agents without this skill | never; rerun `persist-conventions.mjs --write`; the rest is yours |
-| `AGENTS.md` `## Contributing` pointer | points at `CONTRIBUTING.md` | written once by `persist-conventions.mjs` |
+| `AGENTS.md` `## Contributing` pointer and `## Data catalog task entry` rule | reach `CONTRIBUTING.md` and this skill; the rule routes work and authorizes no write | written once by `persist-conventions.mjs`; re-run `--write` to restore a missing one |
 
 ## Rules
 
@@ -118,6 +144,11 @@ Never document tables during setup unless the task asks for it.
    PR why it still holds.
 6. Commit the script and the regenerated pages together.
 
+A repo with no `data-catalog.json`: steps 4 and 5 cannot run, because both exit 2
+without a config. Write the definitions the change needs, say those checks are
+pending, and offer setup once ([First use in a repo](#first-use-in-a-repo)). Do not
+run `init --write` to make them run.
+
 Example: changing `WHERE status = 'POSTED'` to `status IN ('POSTED', 'SETTLED')`
 passes CI, and `drift` reports "filters, joins or CTEs changed; no definition
 changed" until the affected sources say "posted or settled".
@@ -141,6 +172,10 @@ to `data-catalog.json` take effect on the next `init --write`. After a skill upd
 rerun both `init --write` and `persist-conventions.mjs --write` so the repo's copies
 match.
 
+Without `--write`, `init` only prints its plan, so a dry run is always safe. With
+`--write` it is repo setup and needs the user's setup request
+([First use in a repo](#first-use-in-a-repo)).
+
 The scripts import `from catalog_fields import Field, Table` at run time, so the
 module must ship with them like any sibling module (for example `--py-files` on
 `spark-submit`). Check that before merging.
@@ -188,7 +223,8 @@ script is clean when its columns were `unknown`.
 3. Add `CATALOG_TABLE` and `CATALOG_FIELDS` in contract order. Keep the literal
    contract while you write.
 4. Run `generate` until it passes, then derive the contract and run the repo's
-   schema tests (rule 5).
+   schema tests (rule 5). In a repo with no `data-catalog.json` it exits 2: report it
+   pending and offer setup once, and do not run `init --write` for it.
 5. Rerun the audit for that script and fix its writing findings (`repeated-text`,
    `code-in-description`, `long-definition`, `thin-definition`,
    `relative-definition`), or leave one only when the text really belongs in that row.
@@ -201,8 +237,9 @@ empty text.
 
 ## Done when
 
-- `python3 <engine> generate --check` exits 0.
+- `python3 <engine> generate --check` exits 0, or you said it is pending because the
+  repo has no `data-catalog.json`.
 - `python3 <engine> drift` exits 0, or you said in the PR why each listed definition
-  still holds.
+  still holds, or you reported it pending for the same reason.
 - `python3 <engine> audit` has no findings for the tables you touched, or you
   reported the ones left and why.