fastdraw 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -43,34 +43,52 @@ line number, so an agent can fix its own layout before anyone looks at it.
43
43
 
44
44
  ## Getting started
45
45
 
46
- FastDraw needs Node 20 or later.
46
+ FastDraw needs Node 20 or later. Install the skill for your coding agent once; it then works in every
47
+ repository.
48
+
49
+ **Claude Code**, typed in a session:
47
50
 
48
51
  ```
49
- npx fastdraw setup # add FastDraw instructions for this repo's coding agents
50
- npx fastdraw check docs/example.fdraw # report problems, with line numbers
51
- npx fastdraw render docs/example.fdraw # write example.png next to the file
52
- npx fastdraw open docs/example.fdraw # edit in the browser; changes save to the file
52
+ /plugin install fastdraw --marketplace coccor/fastdraw
53
53
  ```
54
54
 
55
- `fastdraw setup` supports Claude Code, Codex, OpenCode and GitHub Copilot. Chat assistants without a
56
- shell can read the language from https://fastdraw.dev/llms.txt.
55
+ On Claude Code older than 2.1.275, run `/plugin marketplace add coccor/fastdraw`, then
56
+ `/plugin install fastdraw@fastdraw`.
57
57
 
58
- ### Updating
58
+ **Codex, OpenCode, Cursor and other agents**, in a terminal:
59
+
60
+ ```
61
+ npx skills add coccor/fastdraw -g
62
+ ```
63
+
64
+ It asks which of your agents to install for. Without `-g` the skill goes into the current repository
65
+ instead, for a team to commit.
59
66
 
60
- The instructions `setup` writes are short: they tell the agent to run `fastdraw guide`, and the guide,
61
- the kinds of diagram, the looks, `check` and `render` all come from the fastdraw that runs. Through
62
- `npx fastdraw` that is the newest release, so most of an update arrives by itself.
67
+ **GitHub Copilot** reads only its instructions file, so run this in the repository:
68
+ `npx fastdraw setup copilot`. Chat assistants without a shell can read the language from
69
+ https://fastdraw.dev/llms.txt.
63
70
 
64
- The instruction files themselves change only when `setup` runs again. Each one carries the version that
65
- wrote it, and when it is older than the fastdraw running, `fastdraw guide` starts with a note asking the
66
- agent to tell you. To update them, run this in the repository; it rewrites the skill and replaces only
67
- FastDraw's own section of `AGENTS.md` or Copilot's instructions:
71
+ Then ask your agent for a diagram. It runs the command-line tool through `npx`, so there is nothing
72
+ else to install:
68
73
 
69
74
  ```
70
- npx fastdraw@latest setup # or name them: setup claude agents copilot
71
- npx fastdraw@latest setup claude --global # if you put the skill in ~/.claude
75
+ npx fastdraw check docs/example.fdraw # report problems, with line numbers
76
+ npx fastdraw render docs/example.fdraw # write example.png next to the file
77
+ npx fastdraw open docs/example.fdraw # edit in the browser; changes save to the file
72
78
  ```
73
79
 
80
+ ### Updating
81
+
82
+ The skill is short: it tells the agent to run `fastdraw guide`, and the guide, the kinds of diagram, the
83
+ looks, `check` and `render` all come from the fastdraw that runs. Through `npx fastdraw` that is the
84
+ newest release, so most of an update arrives by itself. The skill itself updates with
85
+ `/plugin marketplace update fastdraw` in Claude Code (or turn on auto-update for the fastdraw marketplace
86
+ under `/plugin`), and with `npx skills update` elsewhere.
87
+
88
+ Files written by `npx fastdraw setup` (an older way to install, still used for Copilot) carry the version
89
+ that wrote them. When they are older than the fastdraw running, `fastdraw guide` starts with a note asking
90
+ the agent to tell you; run `npx fastdraw@latest setup` in the repository to update them.
91
+
74
92
  If fastdraw is installed on the PATH (`npm install -g fastdraw`), agents use that copy instead of `npx`.
75
93
  `fastdraw guide` checks npm for a newer release at most once a day and says so when there is one; update
76
94
  with `npm install -g fastdraw@latest`. Set `FASTDRAW_NO_UPDATE_CHECK=1` to turn the check off; it is off on CI.
@@ -108,6 +126,12 @@ Written by agents from the guides alone and drawn in the built-in look; sources
108
126
 
109
127
  FastDraw is at version 0.x, and details of the language may still change.
110
128
 
129
+ ## Rust
130
+
131
+ [`fastdraw-render`](crates/fastdraw-render) is the renderer as a Rust crate, for applications that draw
132
+ diagrams without Node. It draws the same SVG as the npm package of the same version, character for character;
133
+ CI checks that on Linux and Windows. See its [README](crates/fastdraw-render/README.md).
134
+
111
135
  ## Contributing
112
136
 
113
137
  See [CONTRIBUTING.md](CONTRIBUTING.md) for building from source, running the tests and the
@@ -6,10 +6,12 @@ Diagrams in this repo are FastDraw files (`.fdraw`), drawn with the look in `.lo
6
6
 
7
7
  - Save a new diagram in `docs/diagrams/` unless the person names another place or the repo already keeps its `.fdraw` files somewhere; never at the top of the repo.
8
8
  - Before writing or changing one, run `fastdraw guide` and follow it; it is the only reference for the language.
9
- - Choose the kind of diagram by what the reader has to understand, not by a word in the request ("request flow" is not a flowchart); `fastdraw guide list` says what each kind shows. Unless the request names the kind, tell the person which kind you would draw and the closest other kind, and ask before drawing.
9
+ - For a diagram of the code, learn the system first: every project or service, how each talks to the others (HTTP clients, queues, shared stores, config), and the paths a request or event takes. Read every project, not only the first. Do not shrink a big system into a few vague boxes; propose an overview plus one diagram per main path, or the one path the person cares about.
10
+ - Choose the kind of diagram by what the reader has to understand, not by a word in the request ("request flow" is not a flowchart; "architecture diagram" is said of any system picture); `fastdraw guide list` says what each kind shows. Unless the request names exactly one kind and nothing in it pulls toward another, ask before drawing: the kind you would draw and the closest other kind, which path when there are several, and the split when the system is too big for one picture.
10
11
  - Finish with `fastdraw check <file>` clean, then run `fastdraw render <file>` and look at the PNG.
11
12
  - `fastdraw check <folder>` and `fastdraw render <folder>` work on every `.fdraw` file under a folder. `fastdraw render <file> --dark` also writes `<file>-dark.png` with the look's dark version, for sites with a dark theme; `--look <name|file.look>` draws with another look without changing the file.
12
13
  - When the diagram is done, always ask the person what to do next: open it in fastdraw.dev (run `fastdraw open <file>` in the background, then give them the link it prints in case no browser window appeared; edits save back to the file), preview the PNG (open it in their image viewer), or nothing. Do not open anything before they choose.
13
14
  - On a docs site (a web page, not a GitHub README), show a diagram with `<fastdraw-diagram src="....fdraw">` from https://fastdraw.dev/embed.js and keep the rendered PNG inside it as the fallback image; see "Embedding a diagram" in FastDraw's README.
15
+ - When a diagram needs vendor icons (Azure, AWS, Google Cloud, Kubernetes, product logos) or a font that does not ship with FastDraw, add them to the look by their https:// address from the recommended sources in `fastdraw guide look`, with a fixed version in the address, rather than downloading files into the repo.
14
16
  - When changing an existing diagram, leave the position, size and styling of existing elements alone unless asked.
15
17
  - If `fastdraw` is not on the PATH, run it as `npx fastdraw`.
package/agents/README.md CHANGED
@@ -1,15 +1,19 @@
1
1
  # Telling agents about FastDraw
2
2
 
3
- All three are thin pointers to `fastdraw guide`, so there is one place to maintain.
4
- `npx fastdraw setup` writes them into a repository; running it again updates them in place.
3
+ There is one skill, in [`../plugins/fastdraw/skills/fastdraw/SKILL.md`](../plugins/fastdraw/skills/fastdraw/SKILL.md).
4
+ It is a thin pointer to `fastdraw guide`, so there is one place to maintain. It reaches agents three ways:
5
5
 
6
- | Agent | Command | What it writes |
6
+ | Agent | How | What it installs |
7
7
  |---|---|---|
8
- | Claude Code | `npx fastdraw setup claude` (`--global` for every repo) | `claude-skill/fastdraw/` as `.claude/skills/fastdraw/` |
9
- | Codex, OpenCode | `npx fastdraw setup agents` | `AGENTS-snippet.md` as a section of `AGENTS.md` |
8
+ | Claude Code | `/plugin install fastdraw --marketplace coccor/fastdraw` | the `fastdraw` plugin from [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json), for the user |
9
+ | Codex, OpenCode, Cursor and others | `npx skills add coccor/fastdraw -g` | the skill in `~/.agents/skills/fastdraw/` and each chosen agent's folder ([skills.sh](https://skills.sh) finds it through the plugin manifest) |
10
10
  | GitHub Copilot | `npx fastdraw setup copilot` | `AGENTS-snippet.md` as a section of `.github/copilot-instructions.md` |
11
+ | A repository that commits its instructions | `npx fastdraw setup claude` or `setup agents` | the skill as `.claude/skills/fastdraw/`, or `AGENTS-snippet.md` as a section of `AGENTS.md` |
11
12
  | Chat assistants | none | Ask it to read https://fastdraw.dev/llms.txt first (or paste that file in), then paste the reply into the editor with "Paste diagram text" |
12
13
 
14
+ The plugin has no `version`, so Claude Code users follow the commits on `main` when they update.
15
+ `claude plugin validate .` checks the marketplace and the plugin.
16
+
13
17
  ## Diagrams on a docs site
14
18
 
15
19
  A README on GitHub can only show the PNG from `fastdraw render`. A docs site (Starlight, Docusaurus,