From c150aaca15978d1b315ee715e80a911b63123d8b Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Thu, 5 Nov 2026 01:29:24 +1100 Subject: [PATCH 1/2] feat(plugin): publish-map-view skill Publishes a map view of a space as a private Claude artifact, refreshes its data and resolves a comment's location back to a node, using structured-context-map-views. --- plugin/.claude-plugin/plugin.json | 2 +- plugin/skills/publish-map-view/SKILL.md | 86 +++++++++++++++++++++++ plugin/skills/structured-context/SKILL.md | 2 + 3 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 plugin/skills/publish-map-view/SKILL.md diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 909e927..4caea36 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "structured-context", - "version": "0.21.0", + "version": "0.21.1", "description": "Structured content authoring for Obsidian — automatic validation hooks, slash commands, and agent skills to keep markdown files compliant with your schema.", "homepage": "https://github.com/mindsocket/structured-context", "repository": "https://github.com/mindsocket/structured-context", diff --git a/plugin/skills/publish-map-view/SKILL.md b/plugin/skills/publish-map-view/SKILL.md new file mode 100644 index 0000000..ec01d46 --- /dev/null +++ b/plugin/skills/publish-map-view/SKILL.md @@ -0,0 +1,86 @@ +--- +name: publish-map-view +description: > + Publish a map view of a structured-context (sctx) space (tree, landscape or XY plot, with parameter controls and + a validation overlay) as a private Claude artifact, refresh its data, and read comments left on it. Use when the + user wants to see, share or discuss their structured content visually, or to update an artifact made this way. + An argument names the space. +--- + +# publish-map-view + +The artifact is a fixed page from the `structured-context-map-views` package. The space's data lives in the +artifact's database, so you never read, build or edit page code, and refreshing is writing the data again. + +Needs the Artifact tool and Bun. Find the space name with `sctx spaces`. + +## Publish + +1. **Pick one version of the package** for both the export and the page, normally the latest: + `npm view structured-context-map-views version`. + +2. **Export the space.** The export holds the graph, validation results (expression rules only; no AI judge runs), the + schema id and the map views that apply to the schema: + + ```bash + bunx structured-context-map-views@ export > export.json + ``` + + Run it where sctx finds the config, or pass `--config `. If `definitions` is empty no map view applies to + the space's schema: tell the user and stop. Keep `export.json` and the files below in your scratchpad. + +3. **Fetch the template and publish it unchanged:** + + ```bash + curl -fsSL https://cdn.jsdelivr.net/npm/structured-context-map-views@/dist/artifact.html > map-view.html + ``` + + Call the Artifact tool with that file, `capabilities: {db: {}}` and icon `map`. Publish it unmodified: it carries its styles and loads its + code and libraries from jsDelivr, pinned to ``. + +4. **Write the space into the artifact database.** The page lists the `spaces` collection, one document per space, + with the three large parts as JSON strings: + + ```bash + jq '{schemaId, graph: (.graph | tojson), validation: (.validation | tojson), definitions: (.definitions | tojson)}' export.json > doc.json + ``` + + Then `write_db` with `db_op: "set"`, `collection: "spaces"`, `doc_id: ""`, `file_path: doc.json`. + +5. **Tell the user** the link and that the space's content (titles, fields, text) is stored in the artifact's + database, visible to whoever the artifact is shared with (private by default). + +To add another space to the same artifact, repeat steps 2 and 4 with its name as `doc_id`; the page offers a picker. + +## Refresh + +Re-run steps 2 and 4 with the same version. Read the existing `spaces/` document with `read_db` and pass +its `version` as `if_version` to `write_db`. Viewers see the new data after a reload. To move to a newer package +version, publish its page to the same artifact URL first. + +If `write_db` is refused for size, tell the user; the page reads one document per space, so the space needs a +narrower selection. + +## Reading comments + +Use the Artifact tool's `comments` action. A thread's `[location]` is the accessible name of the card, in the form +`[] · <view>`; the viewer cuts it at about 45 characters, so the view may be missing. + +1. Read `spaces/<space>` with `read_db` and parse its `graph` string. `graph.nodes[<index>]` is the node: its + fields, content, parent and children. Check that its title matches; if not, the space was refreshed since the + page was loaded, so find the node by title or ask. +2. Its validation messages are in the parsed `validation` string: entries whose `nodeId` is that node's `id`. +3. The location is the card even when the comment was made on something inside it. The viewer's parameter values + (orientation, validation level) are not in it; ask if they matter. + +The database holds the space as of the last write; refresh first if the content has changed since. + +## Troubleshooting + +| Symptom | Cause | Fix | +|---|---|---| +| Blank page, console error "Minified React error #527" | Two copies of React loaded | The page was modified. Fetch it again and republish unmodified | +| "This page needs the artifact database" | Published without the `db` capability | Republish with `capabilities: {db: {}}` | +| "Nothing to show yet" | Step 4 not done, or written to another artifact | Write `spaces/<space>` with this artifact's URL | +| `bunx` can't find `structured-context` | The package's peer isn't installed | `bun install -g structured-context`, then retry | +| `curl` returns 404 | That version isn't published, or predates the page | Use a later `<version>` | diff --git a/plugin/skills/structured-context/SKILL.md b/plugin/skills/structured-context/SKILL.md index eb2878e..12be8e8 100644 --- a/plugin/skills/structured-context/SKILL.md +++ b/plugin/skills/structured-context/SKILL.md @@ -73,6 +73,8 @@ All commands except `validate-file` require a registered space name. Run `sctx - **`dump` is the key debugging tool.** Use it to verify `fieldMap` remapping is working or to inspect exactly what JSONata rules see when a rule fires unexpectedly. +To show a space's map views as a shareable Claude artifact, use the publish-map-view skill. + ## Embedded nodes and Relationships Embedded nodes are nodes that live physically inside another node's file (via tables or lists) rather than as separate files. From 77ff71e5ad59eb69fc05eade9cf3bc6f3048ddd0 Mon Sep 17 00:00:00 2001 From: Roger Barnes <roger@mindsocket.com.au> Date: Thu, 5 Nov 2026 01:40:31 +1100 Subject: [PATCH 2/2] docs(plugin): trim publish-map-view Drop troubleshooting rows and size advice that no run reached or could act on. --- plugin/.claude-plugin/plugin.json | 2 +- plugin/skills/publish-map-view/SKILL.md | 27 ++++++------------------- 2 files changed, 7 insertions(+), 22 deletions(-) diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 4caea36..d12fa3c 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "structured-context", - "version": "0.21.1", + "version": "0.21.2", "description": "Structured content authoring for Obsidian — automatic validation hooks, slash commands, and agent skills to keep markdown files compliant with your schema.", "homepage": "https://github.com/mindsocket/structured-context", "repository": "https://github.com/mindsocket/structured-context", diff --git a/plugin/skills/publish-map-view/SKILL.md b/plugin/skills/publish-map-view/SKILL.md index ec01d46..c2bfe51 100644 --- a/plugin/skills/publish-map-view/SKILL.md +++ b/plugin/skills/publish-map-view/SKILL.md @@ -1,16 +1,12 @@ --- name: publish-map-view description: > - Publish a map view of a structured-context (sctx) space (tree, landscape or XY plot, with parameter controls and - a validation overlay) as a private Claude artifact, refresh its data, and read comments left on it. Use when the - user wants to see, share or discuss their structured content visually, or to update an artifact made this way. + Publish a Claude artifact with a map or tree visualisation of a structured-context (sctx) space, refresh its data, and read comments left on it. Use when the user wants to see, share or discuss their structured content visually, or to update an artifact made this way. An argument names the space. --- -# publish-map-view - The artifact is a fixed page from the `structured-context-map-views` package. The space's data lives in the -artifact's database, so you never read, build or edit page code, and refreshing is writing the data again. +artifact's database, so refreshing is writing the data again. Needs the Artifact tool and Bun. Find the space name with `sctx spaces`. @@ -19,8 +15,7 @@ Needs the Artifact tool and Bun. Find the space name with `sctx spaces`. 1. **Pick one version of the package** for both the export and the page, normally the latest: `npm view structured-context-map-views version`. -2. **Export the space.** The export holds the graph, validation results (expression rules only; no AI judge runs), the - schema id and the map views that apply to the schema: +2. **Export the space.** The export holds the graph, validation results, and the map views that apply to the schema: ```bash bunx structured-context-map-views@<version> export <space> > export.json @@ -35,8 +30,7 @@ Needs the Artifact tool and Bun. Find the space name with `sctx spaces`. curl -fsSL https://cdn.jsdelivr.net/npm/structured-context-map-views@<version>/dist/artifact.html > map-view.html ``` - Call the Artifact tool with that file, `capabilities: {db: {}}` and icon `map`. Publish it unmodified: it carries its styles and loads its - code and libraries from jsDelivr, pinned to `<version>`. + Call the Artifact tool with that file, `capabilities: {db: {}}` and icon `map`. 4. **Write the space into the artifact database.** The page lists the `spaces` collection, one document per space, with the three large parts as JSON strings: @@ -50,7 +44,7 @@ Needs the Artifact tool and Bun. Find the space name with `sctx spaces`. 5. **Tell the user** the link and that the space's content (titles, fields, text) is stored in the artifact's database, visible to whoever the artifact is shared with (private by default). -To add another space to the same artifact, repeat steps 2 and 4 with its name as `doc_id`; the page offers a picker. +To add another space to the same artifact, repeat steps 2 and 4 with its name as `doc_id`. ## Refresh @@ -58,9 +52,6 @@ Re-run steps 2 and 4 with the same version. Read the existing `spaces/<space>` d its `version` as `if_version` to `write_db`. Viewers see the new data after a reload. To move to a newer package version, publish its page to the same artifact URL first. -If `write_db` is refused for size, tell the user; the page reads one document per space, so the space needs a -narrower selection. - ## Reading comments Use the Artifact tool's `comments` action. A thread's `[location]` is the accessible name of the card, in the form @@ -70,17 +61,11 @@ Use the Artifact tool's `comments` action. A thread's `[location]` is the access fields, content, parent and children. Check that its title matches; if not, the space was refreshed since the page was loaded, so find the node by title or ask. 2. Its validation messages are in the parsed `validation` string: entries whose `nodeId` is that node's `id`. -3. The location is the card even when the comment was made on something inside it. The viewer's parameter values - (orientation, validation level) are not in it; ask if they matter. - -The database holds the space as of the last write; refresh first if the content has changed since. +3. The location doesn't include the viewer's parameter values (orientation, validation level); ask if they matter. ## Troubleshooting | Symptom | Cause | Fix | |---|---|---| -| Blank page, console error "Minified React error #527" | Two copies of React loaded | The page was modified. Fetch it again and republish unmodified | | "This page needs the artifact database" | Published without the `db` capability | Republish with `capabilities: {db: {}}` | | "Nothing to show yet" | Step 4 not done, or written to another artifact | Write `spaces/<space>` with this artifact's URL | -| `bunx` can't find `structured-context` | The package's peer isn't installed | `bun install -g structured-context`, then retry | -| `curl` returns 404 | That version isn't published, or predates the page | Use a later `<version>` |