@1aboveio/skills 1.0.14 → 1.0.16

package/skills/app-dev/android-development/scripts/test_maestro_failure.py

@@ -0,0 +1,462 @@
+"""Focused tests for maestro_failure.py: fixture Maestro output, no device, no Maestro.
+
+The fixtures are the artifact layout Maestro's docs describe for a Flow folder
+(manifest.json, commands.json, screenshots/, screen-hierarchy/, logs/), with the
+commands.json entry shape taken from Maestro's source (TestOutputWriter and
+CommandDebugMetadata) because the docs name the fields but show no example.
+
+Run directly (`python3 test_maestro_failure.py`) or through
+`scripts/maestro-failure.test.mjs`, which is what CI discovers.
+"""
+
+import contextlib
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from failure_capture import NATIVE_FAILURE_PREFIX, RECORD_KEYS, RECORD_NAME, read_record  # noqa: E402
+from maestro_failure import (  # noqa: E402
+    MaestroOutputError,
+    convert,
+    describe_command,
+    error_text,
+    main,
+)
+
+SESSION = "2026-07-31_173617"
+FLOW = "checkout_flow"
+CASE = "checkout smoke"
+
+LAUNCHED = {
+    "command": {"launchAppCommand": {"appId": "com.example.app", "optional": False}},
+    "metadata": {
+        "status": "COMPLETED",
+        "timestamp": 1700000000000,
+        "duration": 1200,
+        "sequenceNumber": 0,
+        "depth": 0,
+    },
+}
+
+TAPPED = {
+    "command": {
+        "tapOnElement": {
+            "selector": {"text": "Pay", "optional": False},
+            "label": "Tap Pay",
+            "optional": False,
+        }
+    },
+    "metadata": {
+        "status": "COMPLETED",
+        "timestamp": 1700000001300,
+        "duration": 300,
+        "sequenceNumber": 1,
+        "depth": 0,
+    },
+}
+
+FAILED_RECEIPT = {
+    "command": {
+        "assertConditionCommand": {
+            "condition": {"visible": {"text": "Thank you", "optional": False}},
+            "optional": False,
+        }
+    },
+    "metadata": {
+        "status": "FAILED",
+        "timestamp": 1700000001700,
+        "duration": 30000,
+        "sequenceNumber": 2,
+        "depth": 0,
+        "error": {
+            "message": 'Assertion is false: "Thank you" is visible',
+            "debugMessage": "Screen hierarchy has no match",
+        },
+        "artifacts": [
+            {"type": "SCREEN_HIERARCHY", "path": "screen-hierarchy/step-003-assertCondition.json"},
+            {"type": "SCREENSHOT", "path": "screenshots/step-003-assertCondition.png"},
+        ],
+    },
+}
+
+
+class MaestroOutputCase(unittest.TestCase):
+    def setUp(self):
+        self.directory = tempfile.TemporaryDirectory()
+        self.root = self.directory.name
+        self.output = io.StringIO()
+
+    def tearDown(self):
+        self.directory.cleanup()
+
+    def write(self, relative, payload):
+        path = os.path.join(self.root, relative)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        if isinstance(payload, bytes):
+            with open(path, "wb") as stream:
+                stream.write(payload)
+        else:
+            with open(path, "w", encoding="utf-8") as stream:
+                stream.write(payload)
+        return path
+
+    def write_json(self, relative, payload):
+        return self.write(relative, json.dumps(payload, indent=2))
+
+    def flow(self, steps, name=FLOW, session=SESSION, artifacts=None, manifest=True):
+        """A Flow folder with `steps` in commands.json and the optional artifact files."""
+        base = os.path.join(session, name) if session else name
+        self.write_json(os.path.join(base, "commands.json"), steps)
+        if manifest:
+            self.write_json(
+                os.path.join(base, "manifest.json"),
+                {
+                    "$schema": "https://storage.googleapis.com/maestro-schemas/artifact-manifest/v1.schema.json",
+                    "entries": [
+                        {"kind": "COMMAND_METADATA", "format": "JSON", "relativePath": "commands.json"}
+                    ],
+                },
+            )
+        for relative, payload in (artifacts or {}).items():
+            self.write(os.path.join(base, relative), payload)
+        return os.path.join(self.root, base)
+
+    def failing_flow(self, name=FLOW, session=SESSION):
+        """The worked example: a launch and tap that passed, then a failed assertion."""
+        return self.flow(
+            [LAUNCHED, TAPPED, FAILED_RECEIPT],
+            name=name,
+            session=session,
+            artifacts={
+                "screenshots/step-003-assertCondition.png": b"\x89PNG\r\n\x1a\n",
+                "screen-hierarchy/step-003-assertCondition.json": '{"attributes": {"text": "Pay now"}}',
+                "logs/device-logcat.txt": "07-31 E ActivityManager: no match\n",
+            },
+        )
+
+    def run_convert(self, maestro_dir, **options):
+        options.setdefault("stream", self.output)
+        return convert(maestro_dir, **options)
+
+    def cli(self, *argv):
+        """Run main() and keep its stderr out of the test output."""
+        with contextlib.redirect_stderr(io.StringIO()):
+            return main(list(argv))
+
+    def record(self, evidence_dir):
+        path = os.path.join(evidence_dir, RECORD_NAME)
+        self.assertTrue(os.path.isfile(path), path)
+        with open(path, encoding="utf-8") as stream:
+            return json.load(stream)
+
+    def lines(self):
+        return [line for line in self.output.getvalue().splitlines() if line]
+
+
+class FailingFlowTest(MaestroOutputCase):
+    def test_the_failing_step_becomes_the_record_and_the_line(self):
+        flow_dir = self.failing_flow()
+        failure = self.run_convert(flow_dir)
+
+        self.assertIsNotNone(failure)
+        record = self.record(flow_dir)
+        self.assertEqual(list(record), list(RECORD_KEYS))
+        self.assertEqual(record["case"], FLOW)
+        self.assertEqual(record["step"], 'Assert condition "Thank you"')
+        self.assertEqual(
+            record["error"],
+            'Assertion is false: "Thank you" is visible: Screen hierarchy has no match',
+        )
+        self.assertEqual(record["screenshot"], "screenshots/step-003-assertCondition.png")
+        self.assertEqual(record["uiDump"], "screen-hierarchy/step-003-assertCondition.json")
+        self.assertEqual(record["logcatTail"], "logs/device-logcat.txt")
+        self.assertEqual(record["evidenceDir"], flow_dir)
+        self.assertEqual(record["cleanupErrors"], [])
+        for name in (record["screenshot"], record["uiDump"], record["logcatTail"]):
+            self.assertTrue(os.path.isfile(os.path.join(flow_dir, name)), name)
+
+        lines = self.lines()
+        self.assertEqual(len(lines), 1)
+        self.assertTrue(lines[0].startswith(NATIVE_FAILURE_PREFIX))
+        self.assertEqual(
+            json.loads(lines[0][len(NATIVE_FAILURE_PREFIX) :]),
+            {
+                "case": FLOW,
+                "step": 'Assert condition "Thank you"',
+                "error": record["error"],
+                "evidenceDir": flow_dir,
+            },
+        )
+
+    def test_an_explicit_case_name_is_used(self):
+        flow_dir = self.failing_flow()
+        self.run_convert(flow_dir, case=CASE)
+        self.assertEqual(self.record(flow_dir)["case"], CASE)
+
+    def test_a_labelled_step_uses_the_label(self):
+        labelled = json.loads(json.dumps(FAILED_RECEIPT))
+        labelled["command"] = {
+            "tapOnElement": {
+                "selector": {"text": "Pay", "optional": False},
+                "label": "Tap Pay",
+                "optional": False,
+            }
+        }
+        flow_dir = self.flow([TAPPED, labelled])
+        self.run_convert(flow_dir)
+        self.assertEqual(self.record(flow_dir)["step"], "Tap Pay")
+
+    def test_the_failing_step_wins_over_a_later_one(self):
+        later = json.loads(json.dumps(FAILED_RECEIPT))
+        later["metadata"]["timestamp"] = 1700000009000
+        later["metadata"]["sequenceNumber"] = 3
+        later["metadata"]["error"] = {"message": "second failure"}
+        later["metadata"]["artifacts"] = [
+            {"type": "SCREENSHOT", "path": "screenshots/step-004-tapOnElement.png"}
+        ]
+        flow_dir = self.flow(
+            [TAPPED, FAILED_RECEIPT, later],
+            artifacts={"screenshots/step-003-assertCondition.png": b"png"},
+        )
+        self.run_convert(flow_dir)
+
+        record = self.record(flow_dir)
+        self.assertEqual(record["step"], 'Assert condition "Thank you"')
+        self.assertIn("Assertion is false", record["error"])
+        self.assertEqual(record["screenshot"], "screenshots/step-003-assertCondition.png")
+
+
+class PassingFlowTest(MaestroOutputCase):
+    def test_a_passing_flow_writes_nothing(self):
+        flow_dir = self.flow(
+            [LAUNCHED, TAPPED],
+            artifacts={"logs/device-logcat.txt": "07-31 I ActivityManager: clean\n"},
+        )
+        self.assertIsNone(self.run_convert(flow_dir))
+        self.assertFalse(os.path.exists(os.path.join(flow_dir, RECORD_NAME)))
+        self.assertEqual(self.output.getvalue(), "")
+
+    def test_a_flow_with_no_steps_writes_nothing(self):
+        flow_dir = self.flow([])
+        self.assertIsNone(self.run_convert(flow_dir))
+        self.assertEqual(self.output.getvalue(), "")
+
+    def test_a_folder_without_commands_json_is_not_converted(self):
+        self.write(os.path.join(SESSION, FLOW, "manifest.json"), "{}")
+        with self.assertRaises(MaestroOutputError):
+            self.run_convert(os.path.join(self.root, SESSION))
+        self.assertEqual(self.cli("--maestro-dir", os.path.join(self.root, SESSION)), 2)
+
+    def test_a_missing_folder_is_a_usage_error(self):
+        self.assertEqual(self.cli("--maestro-dir", os.path.join(self.root, "absent")), 2)
+
+
+class ExistingRecordTest(MaestroOutputCase):
+    def test_an_existing_record_is_kept_and_its_line_is_printed(self):
+        flow_dir = self.failing_flow()
+        kept = {
+            "case": CASE,
+            "step": "tap Pay",
+            "error": "RuntimeError: earlier failure",
+            "screenshot": None,
+            "uiDump": None,
+            "logcatTail": None,
+            "evidenceDir": flow_dir,
+            "cleanupErrors": [],
+        }
+        path = self.write_json(os.path.join(SESSION, FLOW, RECORD_NAME), kept)
+
+        failure = self.run_convert(flow_dir)
+
+        self.assertEqual(failure.case, CASE)
+        self.assertEqual(self.record(flow_dir), kept)
+        with open(path, encoding="utf-8") as stream:
+            self.assertIn("earlier failure", stream.read())
+        self.assertEqual(self.lines(), [failure.native_failure_line()])
+
+    def test_a_record_already_in_an_override_evidence_dir_is_kept(self):
+        flow_dir = self.failing_flow()
+        evidence_dir = os.path.join(self.root, "run-evidence")
+        kept = {"case": CASE, "step": None, "error": "RuntimeError: earlier failure", "cleanupErrors": []}
+        self.write_json(os.path.join("run-evidence", RECORD_NAME), kept)
+
+        self.run_convert(flow_dir, evidence_dir=evidence_dir)
+
+        self.assertEqual(self.record(evidence_dir)["error"], "RuntimeError: earlier failure")
+        # The first failure owns the folder, so no Maestro artifact was copied into it.
+        self.assertFalse(os.path.exists(os.path.join(evidence_dir, "screenshots")))
+
+
+class MissingOptionalFilesTest(MaestroOutputCase):
+    def test_absent_artifacts_are_null_and_noted_without_losing_the_error(self):
+        flow_dir = self.flow([TAPPED, FAILED_RECEIPT], manifest=False)
+        self.run_convert(flow_dir)
+
+        record = self.record(flow_dir)
+        self.assertIsNone(record["screenshot"])
+        self.assertIsNone(record["uiDump"])
+        self.assertIsNone(record["logcatTail"])
+        self.assertEqual(record["step"], 'Assert condition "Thank you"')
+        self.assertIn("Assertion is false", record["error"])
+        self.assertEqual(len(record["cleanupErrors"]), 3)
+        self.assertTrue(record["cleanupErrors"][0].startswith("screenshot: "))
+        self.assertTrue(record["cleanupErrors"][1].startswith("uiDump: "))
+        self.assertTrue(record["cleanupErrors"][2].startswith("logcatTail: "))
+
+    def test_the_error_survives_a_listed_artifact_that_is_not_on_disk(self):
+        broken = json.loads(json.dumps(FAILED_RECEIPT))
+        broken["metadata"]["artifacts"] = [
+            {"type": "SCREENSHOT", "path": "screenshots/step-003-assertCondition.png"}
+        ]
+        flow_dir = self.flow([broken], artifacts={"logs/device-logcat.txt": "log\n"})
+        self.run_convert(flow_dir)
+
+        record = self.record(flow_dir)
+        self.assertIsNone(record["screenshot"])
+        self.assertEqual(record["logcatTail"], "logs/device-logcat.txt")
+        self.assertIn(
+            "screenshots/step-003-assertCondition.png is not in the Maestro output",
+            " ".join(record["cleanupErrors"]),
+        )
+        self.assertIn("Assertion is false", record["error"])
+
+    def test_an_unreadable_commands_json_is_not_silently_a_pass(self):
+        flow_dir = self.flow([FAILED_RECEIPT])
+        self.write(os.path.join(SESSION, FLOW, "commands.json"), "{not json")
+        with self.assertRaises(MaestroOutputError):
+            self.run_convert(flow_dir)
+
+
+class SessionFolderTest(MaestroOutputCase):
+    def test_the_session_folder_finds_the_failing_flow(self):
+        self.flow([LAUNCHED, TAPPED], name="login_flow")
+        failing_flow = self.failing_flow()
+        session_dir = os.path.join(self.root, SESSION)
+
+        failure = self.run_convert(session_dir)
+
+        self.assertEqual(failure.evidenceDir, failing_flow)
+        self.assertEqual(self.record(failing_flow)["case"], FLOW)
+
+    def test_the_earliest_failing_step_decides(self):
+        earlier = json.loads(json.dumps(FAILED_RECEIPT))
+        earlier["metadata"]["timestamp"] = 1700000000500
+        earlier["metadata"]["error"] = {"message": "earlier failure"}
+        earlier_dir = self.flow([LAUNCHED, earlier], name="login_flow")
+        later_dir = self.failing_flow(name="checkout_flow")
+
+        self.run_convert(os.path.join(self.root, SESSION))
+
+        self.assertEqual(self.record(earlier_dir)["error"], "earlier failure")
+        self.assertFalse(os.path.exists(os.path.join(later_dir, RECORD_NAME)))
+
+    def test_the_output_root_above_the_session_folder_works(self):
+        failing_flow = self.failing_flow()
+        self.run_convert(self.root)
+        self.assertTrue(os.path.isfile(os.path.join(failing_flow, RECORD_NAME)))
+
+
+class EvidenceDirTest(MaestroOutputCase):
+    def test_an_override_evidence_dir_holds_copies_and_relative_names(self):
+        flow_dir = self.failing_flow()
+        evidence_dir = os.path.join(self.root, "run-evidence")
+
+        failure = self.run_convert(flow_dir, evidence_dir=evidence_dir)
+
+        record = self.record(evidence_dir)
+        self.assertEqual(record["evidenceDir"], evidence_dir)
+        self.assertEqual(failure.evidenceDir, evidence_dir)
+        self.assertEqual(record["screenshot"], "screenshots/step-003-assertCondition.png")
+        self.assertEqual(record["uiDump"], "screen-hierarchy/step-003-assertCondition.json")
+        self.assertEqual(record["logcatTail"], "logs/device-logcat.txt")
+        for name in (record["screenshot"], record["uiDump"], record["logcatTail"]):
+            self.assertTrue(os.path.isfile(os.path.join(evidence_dir, name)), name)
+
+
+class DocumentedShapeTest(MaestroOutputCase):
+    def test_the_documented_flat_entry_shape_is_accepted(self):
+        flow_dir = self.flow(
+            [
+                {"command": "launchApp", "status": "COMPLETED", "duration": 1200, "sequenceNumber": 0},
+                {
+                    "command": "tapOn: Pay",
+                    "status": "FAILED",
+                    "duration": 300,
+                    "sequenceNumber": 1,
+                    "error": "Element not found: Pay",
+                    "artifacts": ["screenshots/step-002-tapOn.png"],
+                },
+            ],
+            artifacts={
+                "screenshots/step-002-tapOn.png": b"png",
+                "logs/device-logcat.txt": "log\n",
+            },
+        )
+
+        self.run_convert(flow_dir)
+
+        record = self.record(flow_dir)
+        self.assertEqual(record["step"], "tapOn: Pay")
+        self.assertEqual(record["error"], "Element not found: Pay")
+        self.assertEqual(record["screenshot"], "screenshots/step-002-tapOn.png")
+        self.assertEqual(record["uiDump"], None)
+
+    def test_a_step_named_screenshot_is_found_without_an_artifacts_list(self):
+        unlisted = json.loads(json.dumps(FAILED_RECEIPT))
+        del unlisted["metadata"]["artifacts"]
+        unlisted["metadata"]["sequenceNumber"] = 1
+        flow_dir = self.flow(
+            [unlisted],
+            artifacts={
+                "screenshots/step-002-assertCondition.png": b"png",
+                "screen-hierarchy/step-002-assertCondition.json": "{}",
+                "logs/device-logcat.txt": "log\n",
+            },
+        )
+
+        self.run_convert(flow_dir)
+
+        record = self.record(flow_dir)
+        self.assertEqual(record["screenshot"], "screenshots/step-002-assertCondition.png")
+        self.assertEqual(record["uiDump"], "screen-hierarchy/step-002-assertCondition.json")
+
+    def test_an_ios_device_log_is_used_when_there_is_no_logcat(self):
+        flow_dir = self.flow(
+            [FAILED_RECEIPT],
+            artifacts={"logs/device-simulator.log": "simulator log\n"},
+        )
+        self.run_convert(flow_dir)
+        self.assertEqual(self.record(flow_dir)["logcatTail"], "logs/device-simulator.log")
+
+
+class ReadingTest(unittest.TestCase):
+    def test_a_command_without_a_label_reads_as_its_type_and_target(self):
+        self.assertEqual(describe_command({"scrollCommand": {"optional": False}}), "Scroll")
+        self.assertEqual(
+            describe_command({"launchAppCommand": {"appId": "com.example.app"}}),
+            'Launch app "com.example.app"',
+        )
+        self.assertEqual(describe_command("tapOn: Pay"), "tapOn: Pay")
+        self.assertIsNone(describe_command(None))
+
+    def test_error_text_keeps_the_debug_detail(self):
+        self.assertEqual(error_text({"error": "boom"}), "boom")
+        self.assertEqual(
+            error_text({"error": {"message": "boom", "debugMessage": "screen has no Foo"}}),
+            "boom: screen has no Foo",
+        )
+        self.assertEqual(error_text({"error": {"message": "boom"}}), "boom")
+        self.assertEqual(error_text({}), "Maestro marked the step FAILED and gave no error message")
+
+    def test_read_record_ignores_a_non_record(self):
+        with tempfile.TemporaryDirectory() as directory:
+            self.assertIsNone(read_record(directory))
+
+
+if __name__ == "__main__":
+    unittest.main()

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.48.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.48.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.48.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.