fmddr-skills 0.6.2 → 0.6.4

package/README.md

@@ -8,7 +8,6 @@ Claude Code, Cursor, and any agent that reads `AGENTS.md`.
 | `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  |
 
 ## Install
 
@@ -49,10 +48,10 @@ Compatible with any agent that picks up `AGENTS.md` from the project root
 
 ```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/
+cp -R skills/fmddr              ~/.claude/skills/
+cp -R skills/fmddr-setup        ~/.claude/skills/
+cp -R skills/fmddr-issue        ~/.claude/skills/
+cp -R skills/fmddr-generate-docs ~/.claude/skills/
 ```
 
 ## Layout
@@ -62,17 +61,17 @@ skills/
 ├── package.json          ← npm package (fmddr-skills)
 ├── bin/
 │   └── install.js        ← npx entry point
+├── fmddr/
+│   └── SKILL.md
 ├── fmddr-setup/
 │   └── SKILL.md
-├── fmddr/
+├── fmddr-generate-docs/
 │   └── SKILL.md
-├── fmddr-issue/
-│   ├── SKILL.md
-│   └── templates/
-│       ├── bug-report.md
-│       └── feature-request.md
-└── fmddr-release/
-    └── SKILL.md
+└── fmddr-issue/
+    ├── SKILL.md
+    └── templates/
+        ├── bug-report.md
+        └── feature-request.md
 ```
 
 ## Updating

package/bin/install.js

@@ -5,7 +5,7 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 
-const ALL_SKILLS = ["fmddr", "fmddr-generate-docs", "fmddr-issue", "fmddr-release", "fmddr-setup"];
+const ALL_SKILLS = ["fmddr", "fmddr-generate-docs", "fmddr-issue", "fmddr-setup"];
 
 const args = process.argv.slice(2);
 const showHelp = args.includes("--help") || args.includes("-h");

package/fmddr/SKILL.md

@@ -58,6 +58,33 @@ the tool:
 | "Search for anything called `…`"                           | `fmddr search "<fts5-query>"`                       |
 | "Explode / split the DDR into files"                       | `fmddr split` or `fmddr split-savexml`              |
 | "What's slow on the server?" / TopCallStats.log analysis   | `fmddr tcs index <log>` then `fmddr tcs slowest` / `hotspots` |
+| "Show me this visually" / "open in canvas" / "visualize"   | `fmddr canvas launch` or `fmddr canvas view --field/--script/--layout/--table/--relationship` |
+
+### Proactively suggest canvas
+
+After any query that surfaces a specific script, field, or table, offer
+canvas as a natural next step — especially if the result has multiple
+references or a complex call chain. Good moments:
+
+- After `fmddr field references` / `script-refs` / `on-layouts` → suggest
+  `fmddr canvas view --field "Table::Field"` to see the full reference graph visually.
+- After `fmddr script show` / `script chain` / `script calls` → suggest
+  `fmddr canvas view --script "Script Name"` to open focused on that script's
+  call graph (called scripts, navigated layouts, touched TOs).
+- After `fmddr layout show` / `on-layouts` results → suggest
+  `fmddr canvas view --layout "Layout Name"` to see the layout's bound TO and
+  which scripts navigate to it.
+- After finding a table or TO (e.g., `fmddr table fields`) → suggest
+  `fmddr canvas view --table "TableName"` to explore relationships, layouts, and scripts.
+- After `fmddr graph path` or a relationship query → suggest
+  `fmddr canvas view --relationship "LeftTO:RightTO"` to visualise the join.
+- If the user says "open in canvas", "show me this visually", or "visualize"
+  → run the appropriate `canvas view` or `canvas launch` command immediately without asking.
+
+`canvas launch` opens a browser tab with the full canvas. `canvas view` supports
+every entity type — `--field`, `--script`, `--layout`, `--table`, `--relationship`
+— and pre-populates the canvas with that entity's reference graph. Pass `--no-open`
+to print the shareable `?v=` URL without opening the browser.
 
 ### Anti-signals (do **not** invoke)
 - The user is working in a FileMaker GUI and just wants to chat about
@@ -232,6 +259,28 @@ fmddr tcs hotspots --by table --limit 20        # busiest tables
 Re-imports of the same log are blocked by SHA; pass `--force` to replace
 or `--reset` to wipe all prior runs first. TCS data survives `fmddr index --force`.
 
+**"Open the visual canvas browser":**
+```sh
+fmddr canvas launch                                       # blank canvas, browse freely
+fmddr canvas launch --script "Batch Process Orders"       # open focused on a script
+fmddr canvas launch --field "Customer::Email"             # open focused on a field
+fmddr canvas launch --table "Customer"                    # open focused on a table
+
+# Pre-populate with the full reference graph for any entity type:
+fmddr canvas view --field "Customer::Email"               # field ref graph
+fmddr canvas view --script "Save Case Request"            # script call/nav graph
+fmddr canvas view --layout "Customer Detail"              # layout context graph
+fmddr canvas view --table "Customer"                      # TO neighbourhood graph
+fmddr canvas view --relationship "Customer:Orders"        # relationship join graph
+fmddr canvas view --relationship 42                       # by numeric id
+
+# Add --no-open to any canvas view command to print the ?v= URL instead:
+fmddr canvas view --field "Customer::Email" --no-open
+```
+Canvas persists node positions across reloads (localStorage). "Reset view"
+clears the saved state. Multiple `--exclude-folder` globs can strip Trash /
+Backup script folders from the `canvas view` graph.
+
 **"Refresh the split tree after a SaveAsXML export, preserving folders":**
 ```sh
 fmddr split-savexml "Profile FLX May 5 2026.xml" \
@@ -240,6 +289,113 @@ fmddr split-savexml "Profile FLX May 5 2026.xml" \
 fmddr index-savexml "Profile FLX May 5 2026.xml" --out ./profile.fmddr.db
 ```
 
+## Canvas — visual DDR explorer
+
+Canvas is a local browser-based node graph that lets users visually explore
+the structure of their FileMaker solution. It runs against the same `.fmddr.db`
+index as the CLI queries — no extra indexing needed.
+
+### What canvas shows
+
+Each entity in the solution is a draggable **node**:
+
+| Node type         | Shows                                                        |
+| ----------------- | ------------------------------------------------------------ |
+| Base table        | All fields with type/badge icons (calc, global, key, etc.)   |
+| Table occurrence  | Fields inherited from the base table                         |
+| Script            | Name, folder, step count; double-click to view steps         |
+| Layout            | Wireframe thumbnail, object count, bound table occurrence     |
+| Relationship      | Left TO ⇄ Right TO with cardinality and join predicates      |
+
+Edges connect nodes to show references: which scripts use a field, which
+layouts are on a table, which scripts call which other scripts, etc.
+
+### When canvas beats text output
+
+Prefer canvas when:
+- The result has **many cross-references** (e.g. a field used in 20 scripts
+  and 8 layouts — the graph shows the shape at a glance).
+- The user wants to **explore** rather than answer a specific question.
+- You want a **shareable snapshot** of a specific view to hand off.
+- The question involves **relationships between multiple entities**
+  (script chains, layout-to-TO linkages, field dependency webs).
+
+Stick to text (`field references`, `script chain`, etc.) when the user
+needs the raw data for scripting, piping, or a quick yes/no answer.
+
+### Command surface
+
+```sh
+# Open a blank canvas (browse freely)
+fmddr canvas launch --db <path>
+
+# Open focused on one entity (canvas starts with that node selected)
+fmddr canvas launch --field "Table::Field"
+fmddr canvas launch --script "Script Name"
+fmddr canvas launch --table "TableName"
+
+# Pre-populate with the full reference graph for any entity type
+# Each command opens the canvas with a ?v= URL pre-loaded with the graph.
+# Add --no-open to print the URL instead of opening the browser.
+
+# Field — root = canonical TO, children = every referencing script/layout/relationship
+fmddr canvas view --field "Table::Field"
+fmddr canvas view --field "Table::Field" --no-open   # print ?v= URL only
+
+# Script — root = script, children = called scripts, navigated layouts, touched TOs
+fmddr canvas view --script "Script Name"
+fmddr canvas view --script "Script Name" --no-open
+
+# Layout — root = layout, children = bound TO, scripts that navigate here
+fmddr canvas view --layout "Layout Name"
+fmddr canvas view --layout "Layout Name" --no-open
+
+# Table occurrence — root = TO, children = relationships, related TOs, layouts, scripts
+# Accepts: TO name, base table name, or numeric id
+fmddr canvas view --table "CustomerTO"
+fmddr canvas view --table "Customer"      # base table name → first TO
+fmddr canvas view --table 42              # numeric TO id
+
+# Relationship — root = relationship, children = left TO and right TO
+# Accepts: numeric id or "LeftTO:RightTO"
+fmddr canvas view --relationship 42
+fmddr canvas view --relationship "Customer:Orders"
+
+# Filter which reference kinds appear in the graph (--field only)
+fmddr canvas view --field "Table::Field" --kinds scripts,layouts
+
+# Strip Trash/Backup/archive script folders from the graph
+fmddr canvas view --field "Table::Field" --exclude-folder "Trash" --exclude-folder "*Backup*"
+fmddr canvas view --script "Script Name" --exclude-folder "*Backup*"
+```
+
+### URL structure
+
+Canvas uses two URL parameters:
+
+**`?v=<token>`** — pre-loaded view. The CLI posts the node/edge payload to the
+local server and gets back a short token. The URL opens with the full graph
+already rendered. Tokens expire after 24 hours; re-run `canvas view` to
+regenerate. Use `--no-open` to print the URL for sharing or bookmarking.
+
+**`?focus=<ref>`** — single-entity focus. Encodes which node to highlight on
+load. Format:
+- `field:<toId>.<fieldId>` — a specific field on a specific table occurrence
+- `to:<toId>` — a table occurrence
+- `script:<scriptId>` — a script
+- `layout:<layoutId>` — a layout
+
+The IDs are numeric synth IDs from the index, not names. `canvas launch
+--field/--script/--table` handles the resolution automatically — agents
+don't need to construct these manually.
+
+### Canvas persists state
+
+Node positions and viewport are saved to `localStorage` (keyed per DB).
+Reloading the browser restores the canvas exactly as the user left it.
+"Reset view" clears the saved state. `?v=` and `?focus=` URLs always take
+precedence over saved state.
+
 ## Filing bugs & feature requests against fmddr
 
 If `fmddr` itself misbehaves, ask the user whether to file an issue at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fmddr-skills",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Claude Code skills for fmddr — FileMaker DDR analyzer",
   "keywords": [
     "claude-code",
@@ -25,7 +25,6 @@
     "fmddr/",
     "fmddr-generate-docs/",
     "fmddr-issue/",
-    "fmddr-release/",
     "fmddr-setup/"
   ],
   "engines": {

package/fmddr-release/SKILL.md

@@ -1,316 +0,0 @@
----
-name: fmddr-release
-description: Cut a new fmddr release end-to-end — bump version, update CHANGELOG, refresh docs if user-visible surface changed, sync and publish the fmddr-skills npm package, 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`)      |
-
-The npm package (`skills/package.json`) has its own version and is bumped
-separately in step 2b. It does not need to match the Python version.
-
-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/ingest.md`
-  (or the relevant commands file)
-- 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.
-
-## Skills — keep in sync with new features
-
-The `skills/` directory in the repo is the source of truth for the
-`fmddr-skills` npm package. The user's installed copies live at
-`~/.claude/skills/fmddr*/SKILL.md` and may have been edited in-session.
-
-**Before every release**, check whether the installed skills differ from
-the repo and sync them:
-
-```sh
-diff ~/.claude/skills/fmddr/SKILL.md skills/fmddr/SKILL.md
-diff ~/.claude/skills/fmddr-setup/SKILL.md skills/fmddr-setup/SKILL.md
-diff ~/.claude/skills/fmddr-release/SKILL.md skills/fmddr-release/SKILL.md
-diff ~/.claude/skills/fmddr-issue/SKILL.md skills/fmddr-issue/SKILL.md
-```
-
-If any differ, copy the installed version (which is more current) into the
-repo:
-
-```sh
-cp ~/.claude/skills/fmddr/SKILL.md skills/fmddr/SKILL.md
-cp ~/.claude/skills/fmddr-setup/SKILL.md skills/fmddr-setup/SKILL.md
-cp ~/.claude/skills/fmddr-release/SKILL.md skills/fmddr-release/SKILL.md
-cp ~/.claude/skills/fmddr-issue/SKILL.md skills/fmddr-issue/SKILL.md
-```
-
-For any release that adds a new command, flag, or workflow:
-- The relevant skill files **must** be updated to document it before
-  shipping (so `npx fmddr-skills` gives agents current knowledge).
-- Key skills to update when ingest commands change: `fmddr/SKILL.md`
-  and `fmddr-setup/SKILL.md`.
-- The release commit should include the updated skill files.
-
-## 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 Python versions and update CHANGELOG
-
-Edit all three files:
-
-- `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))`.
-
-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. Sync and bump the npm skills package
-
-#### 2a. Sync skill files from installed → repo
-
-```sh
-diff ~/.claude/skills/fmddr/SKILL.md skills/fmddr/SKILL.md
-# (repeat for fmddr-setup, fmddr-release, fmddr-issue)
-```
-
-Copy any that differ:
-
-```sh
-cp ~/.claude/skills/fmddr/SKILL.md skills/fmddr/SKILL.md
-cp ~/.claude/skills/fmddr-setup/SKILL.md skills/fmddr-setup/SKILL.md
-cp ~/.claude/skills/fmddr-release/SKILL.md skills/fmddr-release/SKILL.md
-cp ~/.claude/skills/fmddr-issue/SKILL.md skills/fmddr-issue/SKILL.md
-```
-
-#### 2b. Bump the npm package version
-
-Open `skills/package.json` and bump `"version"`. Use the same
-`MINOR.PATCH` convention as the Python package, but they don't need
-to be identical:
-- If any skill content changed → bump the patch.
-- If a new skill was added or removed → bump the minor.
-
-```sh
-# verify the bump
-grep '"version"' skills/package.json
-```
-
-### 3. Commit
-
-Stage all changed files — Python version files, CHANGELOG, and any
-updated skill files and `package.json`:
-
-```sh
-git add pyproject.toml src/fmddr/__init__.py CHANGELOG.md
-git add skills/fmddr/SKILL.md skills/fmddr-setup/SKILL.md \
-        skills/fmddr-release/SKILL.md skills/fmddr-issue/SKILL.md \
-        skills/package.json
-# also add any other modified files (docs, split_savexml.py, cli.py, etc.)
-git commit -m "Release X.Y.Z"
-```
-
-The message is literally `Release X.Y.Z`. The user will push when ready;
-do **not** push without explicit instruction.
-
-### 4. Build Python artifacts
-
-```sh
-python -m build
-ls -lh dist/fmddr-X.Y.Z*
-```
-
-Expected: `fmddr-X.Y.Z.tar.gz` and `fmddr-X.Y.Z-py3-none-any.whl`.
-
-Verify the wheel:
-
-```sh
-python -c "import zipfile; 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"`.
-
-### 5. Push the release commit
-
-Only after the user authorizes:
-
-```sh
-git push origin main
-```
-
-Per the user's global git-push policy, every push needs explicit
-authorization in the current message.
-
-### 6. 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, `v`-prefixed name.
-
-### 7. Upload to PyPI
-
-```sh
-twine upload dist/fmddr-X.Y.Z*
-```
-
-Uses `~/.pypirc` or env vars. **Never** print credentials.
-
-### 8. Publish the npm skills package
-
-```sh
-cd skills
-npm publish
-cd ..
-```
-
-Uses `~/.npmrc` or `NPM_TOKEN` env var for auth. Publishes as
-`fmddr-skills` to the npm registry. If the user wants to dry-run:
-`npm publish --dry-run`.
-
-After publishing, verify:
-```sh
-npm info fmddr-skills version
-```
-
-### 9. 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
-```
-
-Both built artifacts must be attached.
-
-### 10. Verify
-
-```sh
-gh release view vX.Y.Z --repo proofsh/fmddr
-npm info fmddr-skills version
-```
-
-Confirm:
-- GitHub release page lists both `.whl` and `.tar.gz` artifacts.
-- PyPI serves the new version (may take ~30s).
-- npm serves the new `fmddr-skills` version.
-- Git tag points at the `Release X.Y.Z` commit.
-
-Report the release URL, PyPI URL, and npm URL back to the user.
-
-### 11. Upgrade the user's local install
-
-```sh
-uv tool upgrade fmddr
-fmddr --version    # must print X.Y.Z
-```
-
-Optionally reinstall the npm skills to pick up the updated SKILL.md files:
-```sh
-npx fmddr-skills@latest
-```
-
-## When the bugfix is still on a feature branch
-
-1. Create branch `fix/<slug>` (or `feat/<slug>` for minor bumps).
-2. Implement + tests + CHANGELOG entry under `[Unreleased]` only.
-3. PR with `Closes #<issue>`; wait for merge.
-4. `git checkout main && git pull --ff-only`.
-5. Run this skill from step 1.
-
-## Common failure modes
-
-- **Version drift between `pyproject.toml` and `__init__.py`.** The
-  wheel-version check in step 4 is the guardrail — run it.
-- **Skill files out of sync.** Always diff before committing. Shipping
-  stale skills means agents won't know about new commands.
-- **Tagged the wrong commit.** Delete local tag (`git tag -d vX.Y.Z`),
-  retag, force-push the tag — only OK if no one has pulled it yet.
-  Otherwise cut `X.Y.(Z+1)`.
-- **`gh release create` fails on tag not found.** Push the tag (step 6)
-  before step 9.
-- **npm 401 / 403.** Token wrong — tell the user to refresh `~/.npmrc`
-  or `NPM_TOKEN`. Never ask them to paste the token.
-- **Twine 401 / 403.** Same pattern for PyPI.
-
-## Privacy / safety
-
-- Don't run `twine upload`, `npm publish`, or `gh release create`
-  without explicit user go-ahead — all are public, irreversible.
-- Don't print PyPI tokens, npm tokens, or GitHub tokens.
-- Don't force-push `main`. Cut a new patch version instead.