forma-diagrams 0.5.2

package/skills/forma/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: forma
+description: Create, modify, inspect, and export professional diagrams using Forma's local files, CLI, and shared graphical editor.
+---
+
+# Forma
+
+Use `forma` after installation, or `node packages/cli/bin.mjs` from a source checkout; `--help` returns JSON. Run `forma serve --directory ~/Forma` to share a folder and its subfolders with the graphical Library. Reload files before agent edits and refresh the Library afterward. No account or particular agent harness is needed for local use.
+
+If the user gives a hosted origin and agent token, set `FORMA_REMOTE_URL` and `FORMA_AGENT_TOKEN_FILE` (private `chmod 600` file) and use `forma remote` or `forma mcp`. Never use Google cookies. Pull/read the latest revision, preserve IDs and `presentation.nodes`, then push with the bound revision. See [hosted access](references/hosted.md).
+
+Write a version 2 native document with stable node/edge/group IDs, short labels, relationships, and meaningful roles. No diagram type is required. `create --output diagram.forma.json` produces a blank document. The [format reference](../../docs/format.md) explains primitives, composition, style precedence, and patching.
+
+Prefer semantic relationships and automatic layout. Use a composition grid when relative rows and columns carry meaning. Use human position overrides for deliberate exceptions. Nodes default to one connection point per side; set `ports` and edge `sourceIndex` / `targetIndex` when a side needs more. Set edge `path` to pin corners, and preserve an existing path. `align` is left, center, or right; `verticalAlign` is top, middle, or bottom. Adopt an organizational identity with `style diagram.forma.json --system examples/design-systems/atelier.json`; per-element styles remain intact.
+
+Run `validate`, `inspect`, and `render --output diagram.png` on the artifact. If inspect reports `near-alignment`, run `forma align diagram.forma.json --fix`, or align specific nodes with `--left|--center|--right|--top|--middle|--bottom --ids a,b`. Use `--distribute horizontal|vertical --ids a,b,c` to even gaps. Alignment writes pins; preserve them. **View the actual render** and refine its hierarchy, spacing, routing, and readability. Zero diagnostic warnings is useful evidence, not proof of good design. Deliver the native file and export together.
+
+For edits, reload the human's latest saved file and use `patch --patch changes.json`. Preserve IDs and presentation overrides. Never reconstruct a diagram merely to add a node or change a label. `layout --output scene.json` is derived geometry, never the source artifact. CLI exit 1 means invalid input/execution; inspect exits 2 for errors (also warnings with `--strict`).
+
+Use a specialist only if it helps: [architecture](../forma-architecture/SKILL.md), [decisions and flows](../forma-flow/SKILL.md), [organization](../forma-organization/SKILL.md), [entities](../forma-entities/SKILL.md), [timelines](../forma-timeline/SKILL.md), [mind maps](../forma-mindmap/SKILL.md). For an unfamiliar explanation, combine primitives directly; skills are accelerators, not boundaries. See [composition](references/composition.md) when refining.

package/skills/forma/references/composition.md

@@ -0,0 +1,11 @@
+# Refine the composition
+
+Begin with the sentence the diagram should explain. Keep one dominant reading direction or one explicit center. Groups should express ownership, trust, or a conceptual boundary; avoid a container around every object.
+
+Use automatic layout for relationships, a grid when relative rows/columns communicate meaning, and explicit human pins for exceptions. Each shape has one connection point per side. Add `ports` only when several connectors need distinct attachments, and set `sourceIndex` / `targetIndex` to choose one. Leave indexes unset to share the center point; overlapping horizontal or vertical runs are intentional when connectors should read as one line. Set an edge `path` when the route itself carries meaning, and do not clear it during a later edit. Automatic routing keeps an existing bend when it still leaves the same side, and it prefers a detour over a crossing. After pinning, `inspect` reports `near-alignment` when edges sit within 8px of a shared row or column; `forma align --fix` snaps them. Prefer a shared design system and a few semantic roles over repeated element styling. A familiar diagram skill can accelerate this; an unfamiliar explanation can use the same primitives directly.
+
+Before delivery, view the render at a useful reading size. Check title hierarchy, label legibility, balanced whitespace, group headings, connector attachment, and the distinction between primary and secondary information. Check fixed-color overrides under every intended identity; changing a background may require an explicit foreground too. Machine inspection reports symptoms, not aesthetic approval. Do not delete meaningful edges to silence warnings.
+
+Preserve human pins while improving surrounding spacing or structure. Clear only a deliberate position with `{"overrides":{"nodeId":{"position":null}}}` when returning that node to automatic layout is appropriate. Do not clear all overrides as a routine fix.
+
+Favor focused views over tiny text. Use SVG for scalable graphics and PNG for destinations that need raster output. Always retain the native document for future human and agent edits.

package/skills/forma/references/hosted.md

@@ -0,0 +1,28 @@
+# Hosted agent access
+
+Use this only when the user has a hosted Forma workspace and has given you an agent token from **Agent access**. Do not ask for Google credentials or browser cookies.
+
+```sh
+export FORMA_REMOTE_URL=https://diagrams.example.com
+umask 077
+printf '%s\n' "$TOKEN" > "$HOME/.config/forma/agent.token"
+chmod 600 "$HOME/.config/forma/agent.token"
+export FORMA_AGENT_TOKEN_FILE="$HOME/.config/forma/agent.token"
+# Prefer the file. Use FORMA_AGENT_TOKEN only in a secret environment, never both.
+```
+
+```sh
+forma remote whoami
+forma remote list
+forma remote pull path/to/diagram.forma.json --output diagram.forma.json
+# edit the native file with validate / inspect / render
+forma remote push diagram.forma.json
+```
+
+`--create --path folder/name.forma.json` creates a new server file. `--overwrite` on pull replaces a local file and sidecar after you have preserved local edits.
+
+The sidecar `diagram.forma.json.forma-remote.json` binds server, owner, path, and revision. Do not copy it onto a different user, host, or path. A conflict means the file changed on the server: pull into a new output path, reconcile, and push that copy.
+
+`forma mcp` exposes `forma_list_diagrams`, `forma_read_diagram`, `forma_write_diagram`, `forma_inspect_diagram`, and `forma_render_svg` over the same token. Write requires the latest revision; `null` creates a new file only. HTTP `/mcp` exists only if the administrator enabled it; the stdio bridge works without that.
+
+The token can only see that user’s library, optionally limited to one folder prefix. A 401 after a working session usually means expiry or revocation.

package/skills/forma-architecture/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: forma-architecture
+description: Compose software architecture, network boundaries, and data-flow diagrams with Forma.
+---
+
+# Forma architecture
+
+Use [the shared file and CLI workflow](../forma/SKILL.md). This skill supplies composition guidance, not a required diagram type.
+
+Choose one audience and abstraction level. A context or container view is often enough; do not mix individual functions with whole systems. Group by ownership or trust boundary, not merely proximity.
+
+Use nodes for components, directed edges for interactions, and short edge labels for protocol or data. Use `kind` freely for domain meaning; it does not select a renderer. Prefer `layout.direction: RIGHT`, a shared design system, and `role: emphasis` on the primary boundary. Use cylinder geometry only where persistent storage matters. Separate async work with a labeled edge rather than color alone.
+
+Start from [the architecture example](../../examples/gallery/architecture.forma.json) for conventions, replacing content and stable IDs deliberately. Avoid copying its positions; it is automatically laid out. Render, inspect, and verify arrow direction and trust boundaries. See [C4 levels](https://c4model.com/diagrams) for choosing scope.

package/skills/forma-entities/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: forma-entities
+description: Compose entity-relationship and logical data model diagrams with Forma.
+---
+
+# Forma entities
+
+Use [the shared file and CLI workflow](../forma/SKILL.md). This skill supplies composition guidance, not a required diagram type.
+
+Name entities with singular nouns. Decide whether this is a logical model or physical schema before adding attributes. For a physical schema, use descriptions with one attribute per line and explicit PK/FK prefixes; keep only attributes needed to explain the model.
+
+Use rectangles of consistent width, arrowless connectors, and explicit cardinality labels such as `1 → 0..many`. Forma currently uses text cardinality rather than native crow's-foot markers: do not imply strict crow's-foot compliance. Edge labels read from source to target. Put the focal entity at the center of the narrative, with one emphasis role.
+
+Use automatic RIGHT layout first. [The entity example](../../examples/gallery/entities.forma.json) shows keys, attributes, and cardinality. Check that each FK agrees with its relationship. For conventions see [ER notation](https://mermaid.js.org/syntax/entityRelationshipDiagram.html); use Forma JSON rather than Mermaid syntax.

package/skills/forma-flow/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: forma-flow
+description: Compose process flows and decision trees with Forma, including readable exception and retry paths.
+---
+
+# Forma flow
+
+Use [the shared file and CLI workflow](../forma/SKILL.md). This skill supplies composition guidance, not a required diagram type.
+
+Use verbs for actions and questions for decisions. Label each decision branch explicitly; keep the normal path visually direct. Use pill shapes for entry/exit, rectangles for work, and diamonds for decisions only when they help comprehension.
+
+Start with automatic DOWN layout. For a carefully aligned primary path, use grid placement with its steps in one column and exceptions beside it. `appearance.sourcePort` and `targetPort` can select top/right/bottom/left so retry loops enter from the side instead of crossing the normal path. Dashed lines can distinguish feedback, but label them too.
+
+Use a shared design system and roles before specifying colors. Read [the flow example](../../examples/gallery/decision.forma.json) for a complete retry composition. Inspect branch labels and actual rendered routes; do not silently remove an edge to improve the picture.

package/skills/forma-mindmap/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: forma-mindmap
+description: Compose concept maps and exploratory mind maps with Forma.
+---
+
+# Forma mindmap
+
+Use [the shared file and CLI workflow](../forma/SKILL.md). This skill supplies composition guidance, not a required diagram type.
+
+Start with one central question or concept and a small number of distinct branches. Label branches with concepts, not vague category names. Use descriptions for supporting ideas and avoid coloring every node differently.
+
+A one-sided map can use automatic RIGHT layout; a balanced map can use grid cells around the center and straight, arrowless edges. Use an ellipse for the central concept and rectangles for branches. Nested groups are useful only for actual conceptual boundaries.
+
+[The mind map example](../../examples/gallery/mindmap.forma.json) uses a cross composition around one question. Let the design system set the visual identity. Check that the center remains dominant and connectors do not pass through unrelated concepts. This grid approach also works for explanations without a named diagram category.

package/skills/forma-organization/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: forma-organization
+description: Compose readable reporting and ownership hierarchies with Forma.
+---
+
+# Forma organization
+
+Use [the shared file and CLI workflow](../forma/SKILL.md). This skill supplies composition guidance, not a required diagram type.
+
+Put roles or teams in node labels, responsibilities in descriptions. Use DOWN layout and arrowless connectors (`designSystem.edge.arrowEnd: none`) for reporting. Reserve emphasis for the focal leadership role; keep peers equal in size and tone.
+
+Distinguish reporting from collaboration with explicit labels and dashed connectors if both are necessary. Avoid decorative containers around every team. A small hierarchy works automatically; use grid rows for levels and balanced columns for peers when presentation matters more than compactness.
+
+[The organization example](../../examples/gallery/organization.forma.json) demonstrates a small hierarchy with only one size override and semantic roles. Validate that every line represents an actual relationship; whitespace should clarify authority, not imply an extra rank.

package/skills/forma-timeline/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: forma-timeline
+description: Compose phase roadmaps and milestone timelines with Forma.
+---
+
+# Forma timeline
+
+Use [the shared file and CLI workflow](../forma/SKILL.md). This skill supplies composition guidance, not a required diagram type.
+
+Choose whether spacing represents order or elapsed time. State that choice in the diagram description. A composition grid gives equal phase spacing; it must not imply a calibrated time axis. If calendar duration matters, use deliberate positions and label dates clearly.
+
+Use increasing columns for chronology, concise dates in descriptions, and one emphasis role for the current or focal phase. Labels should describe outcomes rather than a list of every task. Use rows for parallel workstreams when needed; keep the same column meaning across rows.
+
+[The timeline example](../../examples/gallery/timeline.forma.json) uses four equal phases and states that they are not time-scaled. Render and check date order, label width, and spacing. This is a diagram, not a scheduling or dependency-analysis engine.