@1aboveio/skills 1.0.13 → 1.0.15

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

@@ -0,0 +1,477 @@
+// Explicit Android project setup. Preview by default; adds only missing guidance.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+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) {
+  const options = { write: false }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--write') options.write = true
+    else if (arg === '--help') options.help = true
+    else if (arg === '--repo-root') {
+      const value = argv[++i]
+      if (!value || value.startsWith('--') || /[\r\n]/.test(value)) throw new Error(`missing or invalid value for ${arg}`)
+      options.repoRoot = path.resolve(value)
+    } else throw new Error(`unknown argument ${arg}`)
+  }
+  return options
+}
+
+function gitOutput(root, args) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' })
+  return result.status === 0 ? result.stdout.trim() : null
+}
+
+function contains(outer, inner) {
+  const relative = path.relative(outer, inner)
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))
+}
+
+function selectRoot(options) {
+  const selected = options.repoRoot ?? gitOutput(process.cwd(), ['rev-parse', '--show-toplevel']) ?? process.cwd()
+  const root = fs.realpathSync(selected)
+  if (!fs.statSync(root).isDirectory()) throw new Error('project root is not a directory')
+  // A home directory holds global agent configuration, not project guidance.
+  if (contains(root, fs.realpathSync(os.homedir()))) {
+    throw new Error('selected root is the home directory or one of its ancestors; pass the project root')
+  }
+  return { root, selected: options.repoRoot ?? null }
+}
+
+function sectionBody() {
+  return fs.readFileSync(fileURLToPath(new URL('../references/android-conventions.md', import.meta.url)), 'utf8').trim()
+}
+
+function resolveTarget(root, name) {
+  const file = path.join(root, name)
+  const stat = fs.lstatSync(file, { throwIfNoEntry: false })
+  if (!stat) return { name, file, target: file, inode: null, nlink: 0, exists: false, link: false }
+  let target
+  try {
+    target = fs.realpathSync(file)
+  } catch {
+    throw new Error(`${name} is a dangling or inaccessible link; repair it before initializing`)
+  }
+  if (!contains(root, target)) throw new Error(`${name} resolves outside the selected project`)
+  const info = fs.statSync(target)
+  if (!info.isFile()) throw new Error(`${name} is not a regular file`)
+  return {
+    name,
+    file,
+    target,
+    inode: { dev: info.dev, ino: info.ino },
+    nlink: info.nlink,
+    exists: true,
+    link: stat.isSymbolicLink(),
+  }
+}
+
+function readGuidance(entry) {
+  if (!entry.exists) return { ...entry, current: null }
+  let bytes
+  try {
+    fs.accessSync(entry.target, fs.constants.R_OK)
+    bytes = fs.readFileSync(entry.target)
+  } catch {
+    throw new Error(`${entry.name} is unreadable`)
+  }
+  let current
+  try {
+    current = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)
+  } catch {
+    throw new Error(`${entry.name} is not valid UTF-8 guidance`)
+  }
+  return { ...entry, current }
+}
+
+// CLAUDE.md is a protected entrypoint. Learn only its identity, never its content.
+function inspectClaude(root) {
+  try {
+    const file = path.join(root, 'CLAUDE.md')
+    const stat = fs.lstatSync(file, { throwIfNoEntry: false })
+    if (!stat) return null
+    const target = fs.realpathSync(file)
+    if (!contains(root, target)) return null
+    const info = fs.statSync(target)
+    if (!info.isFile()) return null
+    return { file, target, inode: { dev: info.dev, ino: info.ino } }
+  } catch {
+    return null
+  }
+}
+
+function sameFile(left, right) {
+  if (!left || !right) return false
+  if (left.target === right.target) return true
+  return Boolean(left.inode && right.inode
+    && left.inode.dev === right.inode.dev && left.inode.ino === right.inode.ino)
+}
+
+function indentWidth(line) {
+  let width = 0
+  for (const char of line) {
+    if (char === ' ') width += 1
+    else if (char === '\t') width += 4 - (width % 4)
+    else break
+  }
+  return width
+}
+
+function stripInlineCode(line) {
+  const runs = [...line.matchAll(/`+/g)]
+  let result = ''
+  let cursor = 0
+  for (let i = 0; i < runs.length; i++) {
+    const opening = runs[i]
+    let closing = i + 1
+    while (closing < runs.length && runs[closing][0].length !== opening[0].length) closing++
+    if (closing === runs.length) continue
+    const end = runs[closing].index + runs[closing][0].length
+    result += line.slice(cursor, opening.index) + ' '.repeat(end - opening.index)
+    cursor = end
+    i = closing
+  }
+  return result + line.slice(cursor)
+}
+
+function stripHtmlComments(line, depth = 0) {
+  let text = ''
+  let index = 0
+  const comments = []
+  while (index < line.length) {
+    const start = line.indexOf('<!--', index)
+    const end = line.indexOf('-->', index)
+    if (start !== -1 && (end === -1 || start < end)) {
+      if (depth === 0) {
+        const close = line.indexOf('-->', start + 4)
+        if (close !== -1) comments.push(line.slice(start, close + 3))
+      }
+      text += depth === 0 ? line.slice(index, start) : ' '.repeat(start - index)
+      index = start + 4
+      depth += 1
+    } else if (end !== -1) {
+      if (depth > 0) {
+        text += ' '.repeat(end + 3 - index)
+        depth -= 1
+      } else {
+        text += line.slice(index, end + 3)
+      }
+      index = end + 3
+    } else {
+      text += depth === 0 ? line.slice(index) : ' '.repeat(line.length - index)
+      break
+    }
+  }
+  return { text, depth, comments }
+}
+
+// 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 scanMarkdown(current) {
+  const lines = []
+  let fence = null
+  let commentDepth = 0
+  let indented = false
+  let previousBlank = true
+  for (const raw of current.split('\n')) {
+    const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw
+    const blank = line.trim() === ''
+    let active = true
+    let text = line
+    let comments = []
+    if (fence) {
+      active = false
+      const close = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line)
+      if (close && close[1][0] === fence.char && close[1].length >= fence.length) fence = null
+    } else if (commentDepth > 0) {
+      const comment = stripHtmlComments(line, commentDepth)
+      text = comment.text
+      commentDepth = comment.depth
+      comments = comment.comments
+    } else {
+      const open = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line)
+      if (open && !(open[1][0] === '`' && open[2].includes('`'))) {
+        fence = { char: open[1][0], length: open[1].length }
+        active = false
+        indented = false
+      } else if (blank) {
+        indented = false
+      } else if (indentWidth(line) >= 4 && (previousBlank || indented)) {
+        active = false
+        indented = true
+      } else {
+        indented = false
+        const comment = stripHtmlComments(stripInlineCode(line))
+        text = comment.text
+        commentDepth = comment.depth
+        comments = comment.comments
+      }
+    }
+    previousBlank = blank
+    lines.push({ raw: line, text: active ? text : '', active, comments })
+  }
+  // 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
+}
+
+// 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`
+}
+
+function hasHeading(current, title) {
+  const lines = markdownView(current)
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (!line.active) continue
+    const atx = /^ {0,3}(#{1,6})(?:[ \t]+(.*?))?[ \t]*$/.exec(line.text)
+    if (atx) {
+      const content = (atx[2] ?? '').replace(/[ \t]+#+[ \t]*$/, '').trim()
+      if (atx[1].length === 2 && content === title) return true
+      continue
+    }
+    const next = lines[i + 1]
+    if (line.text.trim() === title && next && next.active && /^ {0,3}-+[ \t]*$/.test(next.text)) {
+      return true
+    }
+  }
+  return false
+}
+
+function countMarkers(lines, start, end) {
+  const starts = []
+  const ends = []
+  let order = 0
+  for (const line of lines) {
+    for (const comment of line.comments) {
+      if (comment === start) starts.push(order)
+      else if (comment === end) ends.push(order)
+      order++
+    }
+  }
+  return { starts, ends }
+}
+
+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)
+  if (starts.length !== ends.length || starts.length > 1 || (starts.length && starts[0] > ends[0])) {
+    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}`, name)
+}
+
+function linkFrom(from, to) {
+  return path.relative(path.dirname(from.target), to.file).split(path.sep).join('/')
+}
+
+function hasLoader(current, from, to) {
+  const text = markdownView(current).map(line => line.text).join('\n')
+  const links = /\[[^\]\r\n]*\]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+["'][^"'\r\n]*["'])?\s*\)/g
+  for (const match of text.matchAll(links)) {
+    const href = match[1] ?? match[2]
+    if (!href || /^[a-z][a-z\d+.-]*:|^\/\//i.test(href)) continue
+    let target
+    try {
+      const link = new URL(href, pathToFileURL(from.target))
+      if (link.hash && decodeURIComponent(link.hash) !== '#android-development') continue
+      link.hash = ''
+      link.search = ''
+      target = fileURLToPath(link)
+    } catch {
+      continue
+    }
+    if (fs.existsSync(target)) target = fs.realpathSync(target)
+    if (target === to.target) return true
+  }
+  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))
+  if (agents.target === contributing.target) {
+    throw new Error('agent instructions and CONTRIBUTING.md must use distinct files')
+  }
+  if (agents.inode && contributing.inode && agents.inode.dev === contributing.inode.dev
+    && agents.inode.ino === contributing.inode.ino) {
+    throw new Error('agent instructions and CONTRIBUTING.md must use distinct files')
+  }
+
+  for (const entry of [agents, contributing]) {
+    // Reading through a link to the protected entrypoint would read CLAUDE.md.
+    if (claude && entry.link && sameFile(entry, claude)) {
+      throw new Error(`${entry.name} resolves to the protected CLAUDE.md entrypoint; initialization never reads or edits CLAUDE.md`)
+    }
+  }
+
+  const agentsEntry = readGuidance(agents)
+  const contributingEntry = readGuidance(contributing)
+
+  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.`, agentsEntry.name)
+  }
+
+  const contributingText = preserveOrAdd(contributingEntry.current ?? '# Contributing\n', contributingEntry.name, sectionTitle, sectionId, sectionBody())
+
+  const plan = [
+    { ...agentsEntry, next: agentText },
+    { ...contributingEntry, next: contributingText },
+  ]
+
+  for (const entry of plan) {
+    if (entry.current === entry.next) continue
+    if (claude && sameFile(entry, claude)) {
+      throw new Error(`${entry.name} shares its file with the protected CLAUDE.md entrypoint; initialization never edits CLAUDE.md`)
+    }
+    if (entry.exists && entry.nlink > 1) {
+      throw new Error(`${entry.name} is hard-linked to another file; initialization will not change a file it does not exclusively own`)
+    }
+  }
+
+  return plan
+}
+
+function assertWritable(plan) {
+  for (const entry of plan) {
+    if (entry.current === entry.next) continue
+    const target = entry.current === null ? path.dirname(entry.target) : entry.target
+    try {
+      fs.accessSync(target, fs.constants.W_OK)
+    } catch {
+      throw new Error(`${entry.name} is not writable; nothing was changed`)
+    }
+  }
+}
+
+function main(argv) {
+  const options = parseArgs(argv)
+  if (options.help) {
+    console.log(usage)
+    return
+  }
+  const { root } = selectRoot(options)
+  const plan = planInitialization(root)
+  if (options.write) assertWritable(plan)
+  console.log(`android-development init: ${options.write ? 'write' : 'preview only'} (${root})`)
+  for (const entry of plan) {
+    const action = entry.current === entry.next ? 'unchanged' : entry.current === null ? 'create' : 'update'
+    if (options.write && action !== 'unchanged') fs.writeFileSync(entry.target, entry.next)
+    console.log(`  ${entry.name}: ${!options.write && action !== 'unchanged' ? 'would ' : ''}${action}`)
+  }
+  console.log('Existing sections are preserved; initialization does not refresh project policy, install tools, provision devices or authorize delivery actions.')
+}
+
+try {
+  main(process.argv.slice(2))
+} catch (error) {
+  console.error(`android-development init: ${error.message}`)
+  process.exitCode = 2
+}

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.45.2
+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.45.2
+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.45.2
+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.