fmddr-skills 0.4.0

package/README.md

@@ -0,0 +1,83 @@
+# fmddr — Claude Code skills
+
+Four agent skills for working with [`fmddr`](https://github.com/proofsh/fmddr)
+from Claude Code:
+
+| Skill           | Triggers on                                                               | Purpose                                                        |
+| --------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `fmddr-setup`   | "set up fmddr", "install fmddr", "index my DDR", fmddr not found in PATH  | Install fmddr and build the index for a solution               |
+| `fmddr`         | FileMaker / DDR / fmp12 / Profile.xml / "where is X used" / refactor talk | Recognize when to reach for `fmddr` and use it correctly       |
+| `fmddr-issue`   | "report a bug", "file an issue", "feature request" — for fmddr            | Open a high-quality issue at proofsh/fmddr (with severity)     |
+| `fmddr-release` | "release fmddr", "cut a patch", "publish to PyPI"                         | End-to-end release flow: bump, changelog, build, tag, publish  |
+
+**Typical first-time flow:**
+1. `npx fmddr-skills` — installs all four skills
+2. In a Claude Code session: "set up fmddr for my DDR" → `fmddr-setup` activates
+3. Now any FileMaker question → `fmddr` activates automatically
+
+## Install
+
+### npx (no git required)
+
+```sh
+npx fmddr-skills                   # install all four skills (personal)
+npx fmddr-skills fmddr fmddr-setup # install specific skills only
+npx fmddr-skills --project         # project-scoped (.claude/skills/)
+```
+
+### Manual — personal (one user, all projects)
+
+```sh
+mkdir -p ~/.claude/skills
+cp -R skills/fmddr         ~/.claude/skills/
+cp -R skills/fmddr-setup   ~/.claude/skills/
+cp -R skills/fmddr-issue   ~/.claude/skills/
+cp -R skills/fmddr-release ~/.claude/skills/
+```
+
+### Manual — project-scoped (this repo only)
+
+```sh
+mkdir -p .claude/skills
+cp -R skills/fmddr         .claude/skills/
+cp -R skills/fmddr-setup   .claude/skills/
+cp -R skills/fmddr-issue   .claude/skills/
+cp -R skills/fmddr-release .claude/skills/
+```
+
+Project skills override personal skills with the same name.
+
+## Verify
+
+In a Claude Code session, type `/` and look for the skills, or ask
+"is the fmddr skill loaded?" — Claude will list available skills.
+
+## Layout
+
+```
+skills/
+├── package.json          ← npm package (fmddr-skills)
+├── bin/
+│   └── install.js        ← npx entry point
+├── fmddr-setup/
+│   └── SKILL.md
+├── fmddr/
+│   └── SKILL.md
+├── fmddr-issue/
+│   ├── SKILL.md
+│   └── templates/
+│       ├── bug-report.md
+│       └── feature-request.md
+└── fmddr-release/
+    └── SKILL.md
+```
+
+## Updating
+
+```sh
+npx fmddr-skills@latest           # via npm (when a new version is published)
+
+# or from a local clone:
+cd /path/to/fmddr && git pull
+npx --prefix skills . fmddr-skills
+```

package/bin/install.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const ALL_SKILLS = ["fmddr", "fmddr-issue", "fmddr-release", "fmddr-setup"];
+
+// Parse args: `npx fmddr-skills [skill1 skill2 ...]`
+const requested = process.argv.slice(2).filter(a => !a.startsWith("-"));
+const showHelp = process.argv.includes("--help") || process.argv.includes("-h");
+const scopeFlag = process.argv.includes("--project") || process.argv.includes("-p")
+  ? "project"
+  : "personal";
+
+if (showHelp) {
+  console.log(`
+fmddr-skills — install Claude Code skills for fmddr
+
+Usage:
+  npx fmddr-skills                  install all skills (personal)
+  npx fmddr-skills fmddr            install one skill
+  npx fmddr-skills fmddr fmddr-issue install two skills
+  npx fmddr-skills --project        install into .claude/skills/ (project-scoped)
+
+Available skills: ${ALL_SKILLS.join(", ")}
+`);
+  process.exit(0);
+}
+
+const toInstall = requested.length > 0 ? requested : ALL_SKILLS;
+
+// Validate
+for (const name of toInstall) {
+  if (!ALL_SKILLS.includes(name)) {
+    console.error(`Unknown skill: "${name}". Available: ${ALL_SKILLS.join(", ")}`);
+    process.exit(1);
+  }
+}
+
+// Resolve destination
+const dest =
+  scopeFlag === "project"
+    ? path.join(process.cwd(), ".claude", "skills")
+    : path.join(os.homedir(), ".claude", "skills");
+
+fs.mkdirSync(dest, { recursive: true });
+
+// Copy a directory tree recursively
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const dstPath = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, dstPath);
+    } else {
+      fs.copyFileSync(srcPath, dstPath);
+    }
+  }
+}
+
+const skillsRoot = path.join(__dirname, "..");
+let installed = 0;
+
+for (const name of toInstall) {
+  const src = path.join(skillsRoot, name);
+  const dst = path.join(dest, name);
+  copyDir(src, dst);
+  console.log(`  ✓ ${name} → ${dst}`);
+  installed++;
+}
+
+console.log(`\nInstalled ${installed} skill${installed === 1 ? "" : "s"} into ${dest}`);
+console.log("Open a Claude Code session and type / to confirm they appear.");

package/fmddr/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: fmddr
+description: Reach for this skill whenever the user is working with a FileMaker solution — analyzing, auditing, refactoring, documenting, or cleaning up an `.fmp12` file or its DDR (Database Design Report). Triggers on FileMaker Pro, FMP, fmp12, Claris FileMaker, DDR, Profile.xml, Summary.xml, fmxmlsnippet, custom functions, table occurrences, layouts, scripts, ExecuteSQL audits, "where is field X used", "what scripts call this", "find unused fields/scripts/layouts", "what breaks if I delete this", impact analysis, dead-code hunts, FileMaker refactors, and anything that smells like a FileMaker DDR XML (look for `<FMPReport type="Report">`, `<FMPReport type="Summary">`, files ending `.xml` near `.fmp12`, or directories like `<solution>_Files/`). The `fmddr` CLI parses a DDR once into a queryable SQLite index, then answers structural and cross-reference questions in milliseconds with stable JSON output. Also covers filing bug reports and feature requests against proofsh/fmddr on GitHub.
+---
+
+# fmddr — FileMaker DDR analyzer
+
+`fmddr` turns a FileMaker DDR XML into a SQLite index, then answers
+structural questions about the solution: where is this field used, what
+scripts call this script, what breaks if I remove this, what's dead code,
+where do `ExecuteSQL` and `Evaluate` show up. Output is JSON-first and
+stable, so it composes with shell pipelines and agent loops.
+
+This skill exists for two reasons:
+
+1. **Recognize when to reach for it.** A grep over a multi-thousand-script
+   FileMaker solution is the wrong tool. `fmddr` is the right one.
+2. **Use it well.** Index once, query many times, dispatch on the JSON
+   `kind` field rather than parsing prose.
+
+## When to reach for fmddr
+
+Trigger on **any** of these signals — don't wait for the user to name
+the tool:
+
+### Surface signals (filenames / contents)
+- `Profile.xml`, `Summary.xml`, anything matching `<FMPReport type="Report">`
+  or `<FMPReport type="Summary">` at the top of an XML file.
+- A `*.fmp12` file in the working tree (FileMaker solution).
+- An `<solution>_Files/` directory next to a `Summary.xml` (multi-file
+  DDR export).
+- Mentions of "DDR", "Database Design Report", "fmxmlsnippet",
+  "BaseTable", "TableOccurrence", "ScriptStep", "CustomFunction",
+  "ValueList", "ScriptTrigger" — these are FileMaker schema terms.
+- An existing `*.fmddr.db` SQLite file.
+
+### Question shapes
+| If the user asks…                                          | Use…                                                |
+| ---------------------------------------------------------- | --------------------------------------------------- |
+| "Where is `Customer::Email` used?"                         | `fmddr field references` / `script-refs` / `on-layouts` |
+| "What scripts call *Save Case Request*?"                   | `fmddr script called-by`                            |
+| "What does this script call?"                              | `fmddr script calls` / `chain --format mermaid`     |
+| "If I delete this field, what breaks?"                     | `fmddr impact field`                                |
+| "What's dead in this file?"                                | `fmddr unused --kind {field,script,layout,custom_function,value_list,table_occurrence}` |
+| "Where do we use `ExecuteSQL` / `Evaluate`?"               | `fmddr risky-steps --has execute_sql`               |
+| "What custom functions does X use?"                        | `fmddr cf called-by` / `fmddr cf calls`             |
+| "What relationships connect these two TOs?"                | `fmddr graph path <from-TO> <to-TO>`                |
+| "Find scripts named like *_OLD or BACKUP_*"                | `fmddr cleanup-candidates`                          |
+| "Are there orphan refs?"                                   | `fmddr orphans`                                     |
+| "Search for anything called `…`"                           | `fmddr search "<fts5-query>"`                       |
+
+### Anti-signals (do **not** invoke)
+- The user is working in a FileMaker GUI and just wants to chat about
+  design. `fmddr` is for analysis of an exported DDR — it doesn't talk
+  to FileMaker Server.
+- The XML is from a non-FileMaker tool (no `<FMPReport>` root).
+
+## Install fmddr (if missing)
+
+```sh
+fmddr --version || pipx install fmddr
+# or, in a project venv:
+fmddr --version || pip install fmddr
+```
+
+Python 3.11+ required. Optional `[lxml]` extra speeds up parsing on huge
+DDRs.
+
+## The two-step contract
+
+Every analysis follows the same shape:
+
+### 1. Index (once per DDR)
+
+```sh
+fmddr index path/to/Profile.xml --out ./profile.fmddr.db
+# multi-file solution:
+fmddr index path/to/Summary.xml --out ./solution.fmddr.db
+```
+
+`index` is idempotent and streaming — safe to re-run. ~7s per 500MB DDR.
+
+If a `*.fmddr.db` already exists in CWD and is newer than the source XML,
+skip re-indexing.
+
+### 2. Query (millisecond-cheap)
+
+```sh
+fmddr stats --db ./profile.fmddr.db
+fmddr field script-refs "Customer::Email"
+fmddr impact field "Customer::__UID"
+fmddr unused --kind script
+```
+
+DB resolution order: `--db` flag → `$FMDDR_DB` → unique `*.fmddr.db` in
+CWD → error. Set `FMDDR_DB` once at the start of an agent loop and drop
+the flag.
+
+## Output contract
+
+Every command emits a stable envelope. Dispatch on `kind`, not prose.
+
+```json
+{
+  "kind": "field.script-refs",
+  "version": 1,
+  "ddr": {"path": "...", "sha256": "...", "indexed_at": "..."},
+  "query": {"field": {"id": 8712, "name": "...", "table": "..."}},
+  "result": [...],
+  "result_count": 1,
+  "truncated": false
+}
+```
+
+Format flags: `-o {json,jsonl,table,markdown,csv,tsv}`. JSON is the
+default when stdout is not a TTY.
+
+Exit codes worth handling:
+
+- `0` ok
+- `1` not found (no field/script matched the token)
+- `2` ambiguous (qualify with `Table::Field` or use `--by-id`)
+- `64` bad usage
+- `70` internal error
+
+## Common multi-step recipes
+
+**"Find every place this field is used, including inside calc text on
+other fields and CFs":**
+
+```sh
+fmddr field references "Customer::Email"      # all refs, denormalized
+fmddr field script-refs "Customer::Email"     # scripts + step index
+fmddr field on-layouts "Customer::Email"      # layouts
+fmddr field field-refs "Customer::Email"      # other fields whose calcs name it
+```
+
+**"Audit risky scripts":**
+
+```sh
+fmddr risky-steps --has execute_sql
+fmddr risky-steps --has evaluate
+```
+
+**"Map a script's call chain":**
+
+```sh
+fmddr script chain "Save Case Request" --depth 3 --format mermaid
+```
+
+**"What can I safely delete?":**
+
+```sh
+for kind in field script layout custom_function value_list table_occurrence; do
+  fmddr unused --kind "$kind" -o json
+done
+```
+
+## Filing bugs & feature requests against fmddr
+
+If `fmddr` itself misbehaves, ask the user whether to file an issue at
+**https://github.com/proofsh/fmddr**. Use the companion skill
+`fmddr-issue` (same install bundle). It includes:
+
+- Bug-report and feature-request templates with the exact diagnostics
+  to capture.
+- A four-level severity scale (`critical` / `high` / `medium` / `low`)
+  mapped to GitHub labels.
+- A privacy checklist — DDRs leak business logic, so the skill scrubs
+  table/field names, paths, and calc text before posting.
+
+The skill posts via the GitHub MCP `mcp__github__issue_write` (scoped to
+`proofsh/fmddr`), with `gh issue create` as a fallback. Always confirm
+title and body with the user before posting.

package/fmddr-issue/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: fmddr-issue
+description: Companion to the `fmddr` skill. Use when the user wants to report a bug, file an issue, or request a feature for the `fmddr` CLI/library (FileMaker DDR analyzer). Gathers diagnostics, classifies severity for bugs on a four-level scale, then opens an issue at proofsh/fmddr on GitHub. Triggers on phrases like "fmddr bug", "report fmddr issue", "fmddr feature request", "file an issue for fmddr", or when an fmddr command crashed and the user wants it filed upstream.
+---
+
+# fmddr — file a bug report or feature request
+
+Help the user open a high-quality issue at https://github.com/proofsh/fmddr.
+Two paths: **bug report** and **feature request**. Always confirm the title
+and body with the user before posting.
+
+## When to invoke
+
+- User says "report this as a bug to fmddr", "file an issue", "open an
+  fmddr ticket", "this should be fixed upstream", etc.
+- An `fmddr` command just crashed or returned a wrong result and the user
+  wants it tracked.
+- User asks for a new query/command/output format and wants it on the
+  roadmap.
+
+If unsure whether the user wants a bug or a feature, ask once — the two
+templates differ.
+
+## Workflow
+
+### 1. Classify
+
+Ask the user (or infer from context) which one this is:
+
+- **Bug** — something behaves incorrectly, crashes, returns wrong data,
+  or violates the documented contract.
+- **Feature request** — new command, new flag, new output format, new
+  schema, performance ask, docs gap.
+
+### 2. Gather diagnostics (bugs only)
+
+Run these in the user's working directory and capture the output. Skip
+gracefully if a command isn't available.
+
+```sh
+fmddr --version
+python --version
+uname -srm                 # or `sw_vers` on macOS
+fmddr stats --db <their db> -o json   # if they have an indexed DB
+```
+
+For a crash, also collect:
+
+- The exact command they ran (with paths redacted if sensitive).
+- The full traceback or error output.
+- DDR shape if relevant: file size, FileMaker version that produced it,
+  whether it's a single `Profile.xml` or a multi-file `Summary.xml`.
+- Whether `--db`, `$FMDDR_DB`, or auto-discovery was in use.
+
+**Never** include DDR contents, table/field/script names, or proprietary
+schema in the issue body unless the user explicitly approves. DDRs leak
+business logic. Offer to redact identifiers to `Table_A`, `Field_1`, etc.
+
+### 3. Severity scale (bugs only)
+
+Pick one with the user. Map it to a GitHub label.
+
+| Severity     | Label              | When to use                                                                                       |
+| ------------ | ------------------ | ------------------------------------------------------------------------------------------------- |
+| **Critical** | `severity:critical`| Data corruption, wrong query results, index build silently drops rows, security issue. No workaround. |
+| **High**     | `severity:high`    | Common command crashes or returns no results when it should. Workaround exists but is painful.    |
+| **Medium**   | `severity:medium`  | Edge-case crash, output format glitch, misleading error message, perf regression on large DDRs.   |
+| **Low**      | `severity:low`     | Cosmetic, typo, doc inaccuracy, minor UX nit.                                                     |
+
+If the repo doesn't have these labels yet, fall back to the closest
+existing one (`bug`, `enhancement`) and mention the severity in the body.
+
+### 4. Draft the issue
+
+Use the matching template under `templates/`:
+
+- `templates/bug-report.md`
+- `templates/feature-request.md`
+
+Fill in every section. Strip empty headings. Keep titles under 70 chars
+and front-load the affected command:
+
+- Bug: `script chain: crashes on cyclic call graph` ✓
+- Bug: `there is a problem when I run a script chain command` ✗
+- Feature: `field references: add --since flag for time-windowed audits` ✓
+
+### 5. Confirm with the user
+
+Show the rendered title, labels, and body. Ask: "Post this to
+proofsh/fmddr?" Wait for an explicit yes before calling any GitHub tool.
+
+### 6. Post the issue
+
+Use the GitHub MCP tool, scoped to this repo:
+
+```
+mcp__github__issue_write
+  owner:  "proofsh"
+  repo:   "fmddr"
+  action: "create"
+  title:  "<title>"
+  body:   "<rendered template>"
+  labels: ["bug", "severity:high"]   # or ["enhancement"] for features
+```
+
+If `mcp__github__issue_write` is unavailable in the session, fall back to
+`gh issue create --repo proofsh/fmddr --title ... --body-file ... --label ...`.
+Do **not** attempt to push an issue file into the repo as a commit.
+
+After posting, return the issue URL to the user.
+
+## Privacy checklist (run before posting)
+
+- [ ] No DDR file contents pasted (XML snippets, calc text, script bodies).
+- [ ] No real table/field/script/layout names unless the user okayed it.
+- [ ] No file paths containing usernames or client names (`/Users/jane/AcmeCorp/...`).
+- [ ] No customer data in error messages.
+- [ ] Tracebacks scrubbed of absolute paths if they leak identity.
+
+If anything's unclear, ask the user before posting — once an issue is up
+it's effectively public.

package/fmddr-issue/templates/bug-report.md

@@ -0,0 +1,56 @@
+## Summary
+
+<one sentence: what command, what went wrong>
+
+## Severity
+
+**<critical | high | medium | low>** — <one-line justification>
+
+## Reproduction
+
+```sh
+# exact command(s); redact paths and identifiers as needed
+fmddr <subcommand> ...
+```
+
+**Input:** <single Profile.xml | Summary.xml multi-file | indexed DB only>
+**DDR size (if relevant):** <MB>
+**FileMaker version that produced the DDR:** <e.g. FMP 2024 19.6.1>
+
+## Expected behavior
+
+<what should have happened — quote docs/README/--help if applicable>
+
+## Actual behavior
+
+<what happened instead>
+
+```
+<error output / traceback / wrong JSON, fenced>
+```
+
+## Environment
+
+- `fmddr --version`: <x.y.z>
+- Python: <3.11.x>
+- OS: <macOS 14.5 / Ubuntu 22.04 / Windows 11 + WSL2 / ...>
+- Install method: <pip | pipx | from source>
+- Optional extras: <none | [lxml]>
+- DB resolution: <--db flag | $FMDDR_DB | auto-discovery>
+
+## Index metadata (if applicable)
+
+Output of `fmddr stats -o json` (or note "no DB built yet"):
+
+```json
+<paste here>
+```
+
+## Workaround
+
+<known workaround, or "none">
+
+## Additional context
+
+<links to related issues, prior discussion, screenshots of Rich-table
+output if a rendering bug, etc.>

package/fmddr-issue/templates/feature-request.md

@@ -0,0 +1,50 @@
+## Summary
+
+<one sentence: what new capability, on which subcommand>
+
+## Problem / use case
+
+<the concrete analysis you're trying to do that fmddr can't currently
+support, or supports awkwardly. Real-world scenarios beat abstract
+"it would be nice if…" framing.>
+
+## Proposed shape
+
+<sketch the CLI surface — subcommand, flags, a sample invocation — and
+what the JSON envelope `result` array would contain. Don't over-design;
+a rough shape is fine.>
+
+```sh
+fmddr <subcommand> ... --new-flag ...
+```
+
+```json
+{
+  "kind": "<proposed kind>",
+  "result": [
+    { "...": "..." }
+  ]
+}
+```
+
+## Alternatives considered
+
+<existing fmddr commands you tried, shell pipelines that almost work,
+why they fall short>
+
+## Scope hints (optional)
+
+- Which query module would own this? (`tables`, `fields`, `scripts`,
+  `layouts`, `cf`, `graph`, `impact`, `search`)
+- Does it need new index columns or only new SQL over existing tables?
+- Does it need a new ref kind?
+
+## Environment
+
+- `fmddr --version`: <x.y.z>
+- DDR shape this would run against: <single Profile.xml | Summary.xml>
+
+## Additional context
+
+<links, prior art from other DDR tools (FMPerception, BaseElements,
+InspectorPro), references to FileMaker docs>

package/fmddr-release/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: fmddr-release
+description: Cut a new fmddr release end-to-end — bump version, update CHANGELOG, refresh docs if user-visible surface changed, tag, build sdist+wheel, publish to PyPI, and create the GitHub release with artifacts attached. Use when the user says "release fmddr", "cut a patch release", "release X.Y.Z", "ship 0.2.x", "publish to PyPI", "tag a release", or after a bugfix/feature has landed on `main` and they want it shipped. Handles both bugfix → PR → merge → release flows and direct-on-main releases. Knows which docs auto-sync from the repo root (version banner, CHANGELOG page) and which are hand-written and must be updated for new commands/flags/output shapes before shipping.
+---
+
+# fmddr — cut a release
+
+The release process touches **four** version surfaces that must all agree.
+Forgetting one (commonly `src/fmddr/__init__.py`) ships a release where
+`fmddr --version` lies. Walk every step in order; do not skip ahead.
+
+## Version surfaces — keep these in sync
+
+| File                       | Format                       |
+| -------------------------- | ---------------------------- |
+| `pyproject.toml`           | `version = "X.Y.Z"`          |
+| `src/fmddr/__init__.py`    | `__version__ = "X.Y.Z"`      |
+| `CHANGELOG.md`             | `## [X.Y.Z] — YYYY-MM-DD`    |
+| Git tag                    | `vX.Y.Z` (note the `v`)      |
+
+Pre-1.0 versioning per `CHANGELOG.md`: `0.MINOR.PATCH` — `MINOR` bumps for
+new public surface, `PATCH` for bugfixes. Pick the right one before
+starting; don't ask mid-flow.
+
+## Docs — what self-syncs vs. what doesn't
+
+The Fumadocs site under `docs/` auto-syncs two things from the repo root
+at build time, so the release process never edits them by hand:
+
+- `docs/lib/version.ts` reads `version` from `pyproject.toml` → drives
+  the home-page version banner.
+- `docs/scripts/sync-changelog.mjs` mirrors `CHANGELOG.md` →
+  `docs/content/docs/changelog.md` (gitignored). Runs before `dev` /
+  `build`.
+
+So a pure bugfix patch release needs **no** docs commits — once the docs
+deploy fires, both surfaces pick up the new version and changelog
+automatically.
+
+Everything else is hand-written and **must** be updated before cutting
+the release. The doc edits belong in the feature/fix PR, not the
+`Release X.Y.Z` commit. Check each that applies to the release:
+
+- New command, subcommand, or flag → `docs/content/docs/reference/commands.md`
+- Output envelope / JSON shape change → `docs/content/docs/reference/envelope.md`
+- Architectural change (index schema, build sequence) →
+  `docs/content/docs/reference/architecture.md`
+- New workflow worth a guide → `docs/content/docs/guides/*.md`
+- Quickstart-affecting change → `docs/content/docs/quickstart.md`
+- Landing-page copy change → `docs/app/(home)/page.tsx`
+
+If the release contains user-visible changes and the PR didn't touch
+docs, **stop the release** and ask the user whether docs should be
+updated first. Don't ship undocumented public surface.
+
+## Pre-flight
+
+Run these and stop if any fail:
+
+```sh
+git branch --show-current          # must be `main`
+git status                         # must be clean
+git pull --ff-only                 # latest main
+python -m pytest -q                # green
+```
+
+If the release is for a bugfix that's still on a feature branch, finish
+the PR → merge → checkout main → pull first. **Don't release from a
+feature branch.**
+
+Decide the new version (`X.Y.Z`) and today's date (`YYYY-MM-DD`) up front.
+
+## Release steps
+
+### 1. Bump versions and update CHANGELOG
+
+Edit all three files in one commit:
+
+- `pyproject.toml` → `version = "X.Y.Z"`
+- `src/fmddr/__init__.py` → `__version__ = "X.Y.Z"`
+- `CHANGELOG.md`:
+  - Insert a new section `## [X.Y.Z] — YYYY-MM-DD` directly after
+    `## [Unreleased]`.
+  - Move any unreleased entries into it (or write the section fresh if
+    `[Unreleased]` was empty).
+  - Use the same `### Added` / `### Fixed` / `### Changed` headings as
+    prior releases.
+  - Link to the closing PR(s)/issue(s) inline:
+    `([#6](https://github.com/proofsh/fmddr/pull/6))` or
+    `([#5](https://github.com/proofsh/fmddr/issues/5))`.
+
+Sanity-check after editing:
+
+```sh
+grep -E '"0\.[0-9]+\.[0-9]+"|__version__' pyproject.toml src/fmddr/__init__.py
+grep -E '^## \[' CHANGELOG.md | head -3
+```
+
+All three should show the new version; the CHANGELOG's first dated entry
+should be `[X.Y.Z]`.
+
+### 2. Commit
+
+```sh
+git add pyproject.toml src/fmddr/__init__.py CHANGELOG.md
+git commit -m "Release X.Y.Z"
+```
+
+The message is literally `Release X.Y.Z` — match prior commits
+(`Release 0.2.2`, `Release 0.2.3`). The user will push when they're
+ready; do **not** push without explicit instruction.
+
+### 3. Build artifacts
+
+```sh
+rm -f dist/fmddr-X.Y.Z*            # clean any stale local builds
+python -m build
+ls -lh dist/fmddr-X.Y.Z*
+```
+
+Expected output: `fmddr-X.Y.Z.tar.gz` and `fmddr-X.Y.Z-py3-none-any.whl`.
+If `python -m build` isn't available, install it: `pip install build`.
+
+Verify the wheel actually contains the bumped version:
+
+```sh
+python -c "import zipfile, sys; z=zipfile.ZipFile('dist/fmddr-X.Y.Z-py3-none-any.whl'); print(z.read('fmddr/__init__.py').decode())"
+```
+
+Must print `__version__ = "X.Y.Z"`. If it prints the old version, step 1
+missed `__init__.py`.
+
+### 4. Push the release commit
+
+Only after the user authorizes the push:
+
+```sh
+git push origin main
+```
+
+Per the user's global git-push policy, every push needs explicit
+authorization in the current message. A previous "yes, release it"
+doesn't carry forward.
+
+### 5. Tag and push the tag
+
+```sh
+git tag -a vX.Y.Z -m "fmddr X.Y.Z"
+git push origin vX.Y.Z
+```
+
+Annotated tag (`-a`), `v`-prefixed name. Match prior tags (`v0.2.2`,
+`v0.2.3`).
+
+### 6. Upload to PyPI
+
+```sh
+twine upload dist/fmddr-X.Y.Z*
+```
+
+Uses the user's `~/.pypirc` or env vars for credentials. If twine isn't
+installed: `pip install twine`. **Never** print or commit credentials.
+
+If the user wants to dry-run first:
+`twine upload --repository testpypi dist/fmddr-X.Y.Z*`.
+
+### 7. Create the GitHub release
+
+```sh
+gh release create vX.Y.Z \
+  --repo proofsh/fmddr \
+  --title "vX.Y.Z" \
+  --generate-notes \
+  dist/fmddr-X.Y.Z.tar.gz \
+  dist/fmddr-X.Y.Z-py3-none-any.whl
+```
+
+`--generate-notes` produces the "What's Changed" + compare-link body that
+matches prior releases. If the user wants custom notes, replace
+`--generate-notes` with `--notes-file <file>` or `--notes "..."` and
+paste the relevant `CHANGELOG.md` section.
+
+Both built artifacts must be attached — that's how prior releases look
+(`gh release view v0.2.3` shows `.whl` + `.tar.gz` assets).
+
+### 8. Verify
+
+```sh
+gh release view vX.Y.Z --repo proofsh/fmddr
+pip index versions fmddr 2>/dev/null || pip install --dry-run fmddr==X.Y.Z
+```
+
+Confirm:
+- The release page lists both artifacts.
+- PyPI serves the new version (may take ~30s after `twine upload`).
+- The git tag points at the `Release X.Y.Z` commit (`git show vX.Y.Z`).
+
+Report the release URL and PyPI URL back to the user.
+
+### 9. Upgrade the user's local install
+
+The user has `fmddr` installed as a `uv` tool at `~/.local/bin/fmddr`
+(symlink into `~/.local/share/uv/tools/fmddr/`). It is **separate** from
+this repo's `.venv` and won't pick up the new release on its own.
+
+After PyPI confirms the new version is live:
+
+```sh
+uv tool upgrade fmddr
+~/.local/bin/fmddr --version    # must print X.Y.Z
+```
+
+If `uv` isn't available or the install method has changed, fall back
+based on what `which fmddr` resolves to:
+
+- `~/.local/share/uv/tools/...` → `uv tool upgrade fmddr`
+- `pipx`-managed (`pipx list` shows it) → `pipx upgrade fmddr`
+- Plain `pip install --user` → `pip install --user --upgrade fmddr`
+
+Run `fmddr --version` (no path) at the end to confirm the user's `$PATH`
+resolves to the upgraded binary, not the dev `.venv` shim.
+
+## When the bugfix is still on a feature branch
+
+The full flow when starting from an open issue:
+
+1. Create branch `fix/<slug>` (or `feat/<slug>` for minor bumps).
+2. Implement + tests + CHANGELOG entry under `[Unreleased]` only —
+   **don't** bump version numbers in the bugfix commit.
+3. PR with `Closes #<issue>`; wait for merge.
+4. `git checkout main && git pull --ff-only`.
+5. Run this skill from step 1, moving the `[Unreleased]` block into the
+   new versioned section.
+
+This keeps the bugfix PR reviewable on its own merits and the release
+commit small and mechanical.
+
+## Common failure modes
+
+- **Version drift between `pyproject.toml` and `__init__.py`.** Has
+  happened on this repo before. The wheel-version check in step 3 is the
+  guardrail — run it.
+- **Tagged the wrong commit.** If the tag is on a commit that doesn't
+  bump versions (e.g. you tagged the merge commit before bumping
+  `__init__.py`), delete the local tag (`git tag -d vX.Y.Z`), retag, and
+  force-push the tag. Only acceptable if no one has pulled it yet —
+  otherwise cut a `X.Y.(Z+1)` instead.
+- **Forgot to build before tagging.** The tag should point at the commit
+  whose source matches what you upload to PyPI. Build from the tagged
+  commit, not from a dirty tree.
+- **Twine 401 / 403.** Token wrong or scope mismatch. Don't paste the
+  token into chat. Tell the user to refresh `~/.pypirc` or
+  `TWINE_PASSWORD` and re-run step 6.
+- **`gh release create` fails on tag not found.** Push the tag (step 5)
+  before step 7.
+
+## Privacy / safety
+
+- Don't run `twine upload` or `gh release create` without explicit user
+  go-ahead — both are public, irreversible publishes.
+- Don't print PyPI tokens, GitHub tokens, or any credential. If a
+  command fails with an auth error, ask the user to fix their env; never
+  ask them to paste the secret.
+- Don't force-push `main` to "fix" a botched release. Cut a new patch
+  version instead.

package/fmddr-setup/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: fmddr-setup
+description: Install and initialize fmddr for a FileMaker solution. Use when the user asks to "set up fmddr", "install fmddr", "get fmddr ready", "index my DDR", "index my SaveAsXML", or when fmddr commands fail because the CLI isn't installed or no index exists yet. Also triggers when the user drops a .xml DDR/SaveAsXML into the working directory and wants to start analyzing it, or when `fmddr` is not found in PATH.
+---
+
+# fmddr-setup — install fmddr and index a FileMaker solution
+
+This skill gets fmddr installed and an index built in one pass, so the
+user is ready to run any fmddr query immediately after.
+
+## Step 1 — Check whether fmddr is installed
+
+```sh
+fmddr --version
+```
+
+- If it prints a version → already installed, skip to Step 2.
+- If it fails (`command not found`) → install it (Step 1a).
+
+### Step 1a — Install fmddr
+
+Try installers in this order, stopping at the first that works:
+
+```sh
+uv tool install fmddr          # preferred (fast, isolated)
+pipx install fmddr             # good alternative
+pip install --user fmddr       # fallback
+```
+
+After installing, confirm:
+```sh
+fmddr --version
+```
+
+If `fmddr` still isn't on `$PATH` after `uv tool install`, the `uv`
+tools bin dir may not be in `$PATH`. Tell the user:
+```
+Add ~/.local/bin to your PATH, or run: export PATH="$HOME/.local/bin:$PATH"
+```
+
+## Step 2 — Find the DDR or SaveAsXML
+
+Look in the current directory and one level down for:
+
+1. `*.xml` files whose first 200 bytes match `<FMPReport` — these are
+   DDR or SaveAsXML exports.
+2. A `Summary.xml` next to a `*_Files/` directory — multi-file DDR.
+3. Any file the user has already named (trust user-provided paths).
+
+Use `find . -maxdepth 2 -name "*.xml"` if nothing is immediately visible,
+then peek the first line of candidates with `head -c 200`.
+
+**DDR vs. SaveAsXML — how to tell:**
+- `<FMPReport type="Report">` → standard DDR → use `fmddr index`
+- `<FMPReport type="Summary">` → multi-file DDR Summary → use `fmddr index` (auto-detected)
+- File is UTF-16 LE (BOM `FF FE`) AND contains `<FMSaveAsXML` or the
+  `<FMPReport` tag is absent → SaveAsXML → use `fmddr index-savexml`
+- If `fmddr index` fails with a ParseError on a UTF-16 file, retry with
+  `fmddr index-savexml`
+
+## Step 3 — Build the index
+
+```sh
+# Standard DDR (Report or Summary):
+fmddr index path/to/Profile.xml
+
+# SaveAsXML (whole-file clone export):
+fmddr index-savexml path/to/MyFile.xml
+```
+
+This writes `<basename>.fmddr.db` next to the source file (or in the
+current directory if the source is read-only).
+
+Large files (300–700 MB) take 5–20 seconds. Tell the user what's
+happening:
+```
+Indexing… (this takes ~10s for a 300 MB DDR)
+```
+
+## Step 4 — Confirm and orient the user
+
+Run `fmddr stats` to show what was indexed:
+
+```sh
+fmddr stats
+```
+
+Then report a one-line summary, e.g.:
+```
+Index ready: 247 tables, 2304 scripts, 870 layouts — run any fmddr command to start.
+```
+
+Suggest two starter commands based on what's in the file:
+- If the solution has many scripts: `fmddr unused --kind script`
+- If it has a big field count: `fmddr unused --kind field`
+- Always: `fmddr risky-steps --has execute_sql`
+
+## Common problems
+
+| Symptom | Fix |
+|---------|-----|
+| `command not found: fmddr` after `uv tool install` | `export PATH="$HOME/.local/bin:$PATH"` |
+| `ParseError: not well-formed` on index | File is SaveAsXML → use `fmddr index-savexml` |
+| `No .fmddr.db found` on query commands | Index not built yet — run Step 3 |
+| `Ambiguous: multiple scripts match` on a query | Add the script ID: `fmddr script show 900` |
+| Very slow index on a 600 MB file | Normal — large SaveAsXML files take up to 30s |

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "fmddr-skills",
+  "version": "0.4.0",
+  "description": "Claude Code skills for fmddr — FileMaker DDR analyzer",
+  "keywords": ["claude-code", "claude", "skills", "filemaker", "fmddr", "ddr"],
+  "homepage": "https://fmddr.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/proofsh/fmddr.git",
+    "directory": "skills"
+  },
+  "license": "MIT",
+  "bin": {
+    "fmddr-skills": "./bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "fmddr/",
+    "fmddr-issue/",
+    "fmddr-release/",
+    "fmddr-setup/"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}