diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 020a32e..1ace1a0 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,6 +1,6 @@
blank_issues_enabled: false
contact_links:
- name: Security vulnerability
- url: https://github.com/hector-ae21/rup-flow/security/advisories/new
+ url: https://github.com/hector-ae21/rup-flow-docs/security/advisories/new
about: Report vulnerabilities and exposed credentials privately.
diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
index 687eacb..ae2fc2f 100644
--- a/.markdownlint-cli2.yaml
+++ b/.markdownlint-cli2.yaml
@@ -14,6 +14,7 @@ config:
- sup
- figure
- figcaption
+ - a
- svg
globs:
- "**/*.md"
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 49cd74d..40be810 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -18,7 +18,7 @@ private information, and conduct inappropriate in a professional setting.
## Enforcement
Report unacceptable behavior privately through the contact methods in the
-[rup-flow security policy](https://github.com/hector-ae21/rup-flow/security/policy).
+[security policy](SECURITY.md).
Project maintainers may remove, edit, or reject contributions and communication
that do not align with this code, and will respect the reporter's privacy.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d96d86b..ec5a7e0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,12 +13,10 @@ procedure easier to follow, a statement more precise or a page easier to find.
## What to write
-- Describe released behaviour of the free edition. Roadmap items are labelled as
- such.
+- Describe released behaviour of both editions. Roadmap items are labelled as such.
- Procedures state prerequisites, the result and how to recover.
-- Describe rup-flow Pro at feature level only. A reader must not be able to
- recreate a Pro capability from this site: no Pro commands, flags,
- configuration keys, templates or step-by-step procedures.
+- Mark everything that belongs to Pro: `edition: pro` and `since` in the front matter of a page,
+ the Pro tag in tables and steps.
- Examples contain no credentials or private data.
## Verify locally
diff --git a/README.md b/README.md
index b5be8eb..3e4d8c3 100644
--- a/README.md
+++ b/README.md
@@ -2,10 +2,10 @@
[](https://github.com/hector-ae21/rup-flow-docs/actions/workflows/pull-request.yml)
-Versioned documentation for [rup-flow](https://github.com/hector-ae21/rup-flow),
-the skill that turns requirements into RUP documentation with your AI coding
-agent. It documents the free edition completely and describes rup-flow Pro at
-feature level.
+Versioned documentation for rup-flow,
+the skill that turns requirements into RUP documentation with any AI coding
+agent. It documents the free edition and rup-flow Pro, and marks every page, row and step
+that belongs to Pro.
Read it at . The site is versioned
by the free edition's `MAJOR.MINOR`; each approved publication also gets an
@@ -39,12 +39,13 @@ site with `.venv/bin/mkdocs serve`.
## Rules
-- Document released behaviour. The free edition is documented completely.
-- Describe Pro at feature level only. Never write content that would let someone
- recreate a Pro capability: no Pro commands, flags, configuration keys,
- templates or step-by-step procedures.
-- The catalogue on the comparison page comes from `editions.json` of the free
- repository. Update it there first, then here.
+- Document released behaviour of both editions, in detail.
+- Mark everything that belongs to Pro: `edition: pro` and `since` in the front matter of a
+ page, and the Pro tag in tables and steps. Pages without the mark describe the free edition.
+- Never document behaviour that does not exist.
+- Diagrams are PlantUML sources drawn in a light and a dark look; edit the source, not the SVG.
+- The catalogue on the comparison page comes from `editions.json` of the skill (private
+ repository). Update it there first, then here.
- Examples contain no real credentials or private data.
## Versions
diff --git a/SECURITY.md b/SECURITY.md
index dd93664..b87293b 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,18 +1,14 @@
# Security policy
-This repository holds documentation sources and tooling. It processes no user
-data and publishes no secrets.
+This repository holds documentation sources and tooling. It processes no user data and publishes no secrets.
## Reporting a vulnerability
-Use GitHub private vulnerability reporting: **Security → Report a vulnerability**
-on this repository, or on
-[hector-ae21/rup-flow](https://github.com/hector-ae21/rup-flow/security/advisories/new)
-for the skill itself. Do not open a public issue for a vulnerability or an
-exposed credential.
+Use GitHub private vulnerability reporting: **Security → Report a vulnerability** on this repository. It reaches the maintainer for the documentation and for the skill. Do not open a public issue for a vulnerability or an exposed credential.
## Scope
- Content that suggests an unsafe practice.
- A credential or private data committed by mistake.
- A vulnerability in the build or publication workflows.
+- A vulnerability in the rup-flow skill or its packages.
diff --git a/cspell.json b/cspell.json
index 4466c17..f9fc7f9 100644
--- a/cspell.json
+++ b/cspell.json
@@ -64,6 +64,22 @@
"lms",
"Lifecycles",
"nodesep",
- "ranksep"
+ "ranksep",
+ "nrup",
+ "usecases",
+ "opencode",
+ "clinerules",
+ "kilocode",
+ "junie",
+ "amazonq",
+ "grayscale",
+ "rrggbb",
+ "ddark",
+ "windsurf",
+ "cline",
+ "roo",
+ "aider",
+ "mjs",
+ "ifdef"
]
}
diff --git a/docs/architecture/behavior.md b/docs/architecture/behavior.md
new file mode 100644
index 0000000..1ee43d6
--- /dev/null
+++ b/docs/architecture/behavior.md
@@ -0,0 +1,67 @@
+---
+title: Runtime behaviour
+description: What happens, step by step, when the agent adds a use case, renders diagrams and starts the CLI.
+---
+
+# Runtime behaviour
+
+Three scenarios show how the pieces cooperate. Each one is a rule you can rely on.
+
+## Adding a use case
+
+
+
+
+
+
+
+
+1. The person states the use case in plain language.
+2. The agent runs `new use-case` with what it knows: actor, package, goal.
+3. The CLI chooses the next free identifier by reading the existing cards, writes only the
+ files that do not exist yet, and regenerates the index from the cards.
+4. The agent fills the card from what the person said. Whatever the person did not say
+ becomes an open question.
+5. The agent runs `check` and reports the files, the open questions and what was not
+ checked.
+
+Two properties follow. Running the command twice never overwrites work, because existing
+files are skipped. And the index is always derived from the cards, never edited by hand.
+
+## Rendering diagrams
+
+
+
+
+
+
+
+
+- A diagram is up to date when its SVG is newer than its source; `--force` redraws
+ everything, and a change of palette does so automatically.
+- A failure of one diagram never stops the others. The report lists what was drawn,
+ what was skipped and what failed, and the exit code is `1` when anything failed.
+- The SVG is written to a temporary file and moved into place, so an interrupted run
+ never leaves half an image.
+
+## Starting the CLI
+
+
+
+
+
+
+
+
+The edition is decided once, at start, by one file. A command that needs Pro never
+half-runs in the free edition: it stops before doing any work and says which part is
+missing.
+
+## The report
+
+Every command ends with a report: a title, then labelled values and lists. The same shape
+is used by all commands so an agent can read any of them the same way.
+
+## Related
+
+[Structure](structure.md) · [Editions and the extension point](editions.md)
diff --git a/docs/architecture/decisions.md b/docs/architecture/decisions.md
new file mode 100644
index 0000000..c82bafb
--- /dev/null
+++ b/docs/architecture/decisions.md
@@ -0,0 +1,85 @@
+---
+title: Quality and decisions
+description: The qualities the rup-flow design protects and the decisions behind it, with the reasons and the alternatives that were rejected.
+---
+
+# Quality and decisions
+
+## Qualities
+
+| Quality | How it is protected |
+| --- | --- |
+| Portability | The skill follows the open Agent Skills format; adapters isolate each agent; the CLI needs only Node.js |
+| Honesty | Provenance marks, the rule against inventing content, open questions, and a CLI that refuses what the edition lacks |
+| Repeatability | Commands skip what exists, derive indexes from the cards, and record the render state |
+| Safety | Writes only inside chosen folders; local, sandboxed rendering; no network calls of its own |
+| Maintainability | One reason to change per module; a catalogue and validation that stop the editions drifting |
+| Compatibility | One CLI and one skill structure for both editions, so a project moves from free to Pro without renaming |
+
+## Decisions
+
+Each decision states the context, the choice and what it costs.
+
+### D-01 A skill plus a CLI, not a skill alone
+
+**Context.** An agent writes good prose and bad boilerplate: it renumbers identifiers,
+forgets to refresh an index, draws diagrams it cannot see.
+**Decision.** Mechanical work is deterministic code behind a command line; judgement stays
+with the agent.
+**Cost.** The agent must be able to run a command; an agent that cannot, writes documents
+without rendering or checking and must say so.
+
+### D-02 No runtime dependencies
+
+**Context.** The skill is unzipped into any folder on any machine.
+**Decision.** The CLI uses only the Node.js standard library.
+**Cost.** Small utilities are written in the project instead of imported.
+
+### D-03 PlantUML in a local container, not a hosted service
+
+**Context.** Diagrams describe private systems.
+**Decision.** Rendering goes to a container on the loopback interface, with a sandboxed
+profile.
+**Cost.** Docker is needed to draw; without it the sources are still written and can be
+drawn later.
+
+### D-04 One CLI, two editions, selected by a file
+
+**Context.** Forking the code for a paid edition doubles every fix.
+**Decision.** The free CLI loads an extension when it finds `scripts/pro/index.mjs`; the Pro
+package is the free skill with an overlay.
+**Cost.** The free tree must expose clean extension points and stay free of Pro code, which
+validation enforces.
+
+### D-05 Refuse, do not degrade
+
+**Context.** A free edition that quietly produces a weaker version of a Pro artifact would
+mislead.
+**Decision.** Anything outside the edition stops with a message that names Pro, or is
+counted and listed; the skill tells the agent not to improvise it.
+**Cost.** Some requests end earlier than a user expects, which is the point.
+
+### D-06 Numbered folders that never change
+
+**Context.** Users move from free to Pro.
+**Decision.** Both editions use the same discipline folders; Pro fills the rest.
+**Cost.** The free tree shows folders that Pro uses and the free edition leaves empty or
+absent.
+
+### D-07 Light and dark diagrams are two files
+
+**Context.** One SVG cannot be readable on both a white and a dark page.
+**Decision.** Documentation diagrams are drawn twice from one source with two palettes and
+the page shows the one that matches its theme.
+**Cost.** Twice the files, checked as a pair by the build.
+
+### D-08 Instruction files for agents without skills
+
+**Context.** Many agents read a rules file instead of Agent Skills.
+**Decision.** A command writes a small, delimited block into the file each tool reads and
+replaces only that block.
+**Cost.** The list of targets follows each tool's conventions and needs maintenance.
+
+## Related
+
+[Structure](structure.md) · [Delivery and branches](delivery.md)
diff --git a/docs/architecture/delivery.md b/docs/architecture/delivery.md
index 730f8f7..4cab484 100644
--- a/docs/architecture/delivery.md
+++ b/docs/architecture/delivery.md
@@ -1,39 +1,64 @@
---
title: Delivery and branches
-description: How rup-flow is released, which branches exist and how this documentation is published.
+description: How rup-flow is branched, versioned and released, and how this documentation is published.
---
# Delivery and branches
-## Repository
+## One repository, two branches
-| Branch | What it is | Who writes it |
-| --- | --- | --- |
-| `main` | Source of truth; protected, changes arrive through pull requests with `CI complete` | Pull requests |
-| `claude-plugin` | The plugin payload the marketplace and the directory read | The release workflow, on each `vX.Y.Z` tag |
-| `docs-assets` | The README screenshot and the PNG icon | The maintainer, when images change |
+The source lives in one private repository with two long-lived branches. The packages built
+from them are what is published; the source is not.
-The plugin tree contains no binary files; images that need one live on
-`docs-assets` and are linked by address.
+
-## Release
+
+
-1. Move the `Unreleased` entries of the changelog to a new version section.
-2. Bump the version in `package.json`, the plugin manifest and `SKILL.md`.
-3. Merge to `main`, then tag `vX.Y.Z`.
-4. The release workflow validates and tests, publishes `rup-flow-skill.zip` on the
- GitHub release and regenerates the `claude-plugin` branch.
+
-## Continuous integration
+| Branch | Holds | Tag | Package |
+| --- | --- | --- | --- |
+| `main` | The free edition | `vMAJOR.MINOR.PATCH` | `rup-flow-free-.zip` |
+| `pro` | `main` plus the `pro/` folder: overlay, build, tests, license | `pro-vMAJOR.MINOR.PATCH` | `rup-flow-pro-.zip` |
+
+`main` is complete and never contains anything from Pro. After a change lands in `main` it is
+merged into `pro`, so the Pro build always contains a known free version, and the Pro package
+states it. Both branches only take changes through pull requests with `CI complete`.
+
+## From change to package
+
+
+
+
+
+
+
| Job | Checks |
| --- | --- |
-| Validate | Skill format, manifests, links, no binaries, no Pro templates |
-| Test | The CLI test suite on Linux and Windows with Node.js 18 and 22 |
+| Validate | Skill format, links, no sensitive-looking names, no Pro templates in the free tree |
+| Test | The CLI suite on Linux and Windows with Node.js 18 and 22 |
| Render | `init`, `new use-case`, `render` and `check` against a real PlantUML server |
+| Pro tests | The built Pro skill: every command, the explorer, the example project and the package |
+
+The release workflow checks that the tag equals the version in the files, runs the tests,
+builds the package and attaches it to the GitHub release with the changelog section as its
+notes. A release is never overwritten.
+
+## Version identity
+
+A package names its version in three places that must agree: the file name, `SKILL.md`
+metadata and the output of `RUP version`. Pro also names the free version it contains. See
+[Versioning and URLs](../releases/versioning.md).
## This documentation
-The site is built with MkDocs Material and published with Mike. The version
-selector uses the free edition's `MAJOR.MINOR`. Each approved publication gets an
-immutable tag and a GitHub release. See [Versioning and URLs](../releases/versioning.md).
+The site is built with MkDocs Material and published with Mike, from the public
+`rup-flow-docs` repository. The version selector uses the free edition's `MAJOR.MINOR`, and
+Pro is documented on the line of the free version it contains. Each approved publication gets
+an immutable tag and a GitHub release.
+
+## Related
+
+[Editions and the extension point](editions.md) · [Quality and decisions](decisions.md)
diff --git a/docs/architecture/editions.md b/docs/architecture/editions.md
index dbd26c7..3c6f85c 100644
--- a/docs/architecture/editions.md
+++ b/docs/architecture/editions.md
@@ -1,19 +1,26 @@
---
title: Editions and the extension point
-description: How one command line serves both the free and the Pro edition.
+description: How one command line serves both the free and the Pro edition, and how the Pro package is assembled from the free skill.
---
# Editions and the extension point
There is one CLI. Which edition you run depends on one file.
-
+## Assembly
-
+
+
+
+
-[Open the PlantUML source](../assets/diagrams/sources/editions-overlay.puml)
+The free package is the free skill, zipped. The Pro package is a copy of the free skill with
+the Pro overlay laid over it and the folder renamed `rup-flow-pro`. Files in the overlay
+replace files of the same path, which is how Pro swaps a short template for its full
+version without a second code path. The build also records the Pro version and the free
+version it contains.
## Detection
@@ -21,11 +28,8 @@ At start, the CLI looks for `scripts/pro/index.mjs` next to itself:
| File present | Edition | Behaviour |
| --- | --- | --- |
-| No | Free | Runs on its own. Anything outside the edition stops with a message that names Pro. |
-| Yes | Pro | The extension adds capabilities and the CLI uses them. |
-
-The extension is not part of this repository. It is added when the Pro package
-is built.
+| No | Free | Runs on its own. Anything outside the edition stops with a message that names Pro |
+| Yes | Pro | The extension adds capabilities and the CLI uses them |
## What the extension adds
@@ -35,26 +39,29 @@ The extension is a module that the CLI calls at defined points:
| --- | --- | --- |
| Templates | Only the free templates exist; `init` and `new use-case` skip the rest and count them | The remaining templates are present and are written |
| Rendering | Default PlantUML look | Palettes, Mermaid, PNG previews |
-| Use-case index | Table | Table and the use-case diagrams |
-| Commands | Free commands | Plus `themes`, `explore`, `scan` |
-| Configuration | Mermaid and non-`svg` outputs are rejected | Accepted |
+| Use-case index | A table | A table and the use-case diagrams |
+| Commands | The free commands | Plus `themes`, `explore` and `scan` |
+| Configuration | A Mermaid language or a non-`svg` output is rejected | Accepted |
+| Instructions | Lists the free commands | Lists all commands |
+| Version | Reports the free version | Reports the Pro version and the free version it contains |
## The catalogue
-`editions.json` lists every diagram, document, workflow and tool with its tier.
-`RUP editions` prints it and marks what is available in the installation. The
-documentation pages for the catalogue are generated from the same list, so the
-CLI and this site cannot disagree.
+`editions.json` lists every diagram, document, workflow and tool with its tier. `RUP editions`
+prints it and marks what the installation includes. The comparison page of this site is
+generated from the same list, so the CLI and the documentation cannot disagree.
## Rules for contributors
-- A capability that is not in the free edition must stop with a message that
- names Pro and exit with code `1`, or appear in the `available in Pro` line. It
- never fails silently and is never reimplemented in the free tree.
+- A capability that is not in the free edition stops with a message that names Pro and
+ exits with code `1`, or appears in the `available in Pro` line. It never fails silently
+ and is never reimplemented in the free tree.
- Every new artifact gets an entry in `editions.json`.
- Validation rejects Pro templates inside the free skill.
+- Behaviour specific to one edition is selected by the presence of the extension, never by
+ a setting a user could flip.
-## Why an overlay
+## Related
-The Pro package is the free skill with the extension laid over it, renamed
-`rup-flow-pro`. Nothing is forked, so a fix in the free edition reaches both.
+[Runtime behaviour](behavior.md) · [Delivery and branches](delivery.md) ·
+[Free and Pro compared](../pro/compare.md)
diff --git a/docs/architecture/index.md b/docs/architecture/index.md
index 1e31dec..75d9fba 100644
--- a/docs/architecture/index.md
+++ b/docs/architecture/index.md
@@ -1,77 +1,103 @@
---
title: Architecture
-description: How the free rup-flow skill is built, what is inside the package and how the Pro extension attaches to it.
+description: Why rup-flow is a skill plus a small command line, how its parts fit together, and where each design decision is recorded.
---
# Architecture
-rup-flow is a skill plus a small command line. It has no runtime dependencies
-and no service of its own.
+rup-flow is a skill plus a small command line. The skill tells an AI coding agent what to
+do and what never to do; the command line does the work that must be exact: creating
+structure, keeping an index in sync, drawing diagrams and checking the result. There is
+no service, no account and no dependency to install beyond Node.js 18.
-## System context
+This section explains how the pieces fit, in the order a newcomer needs them.
-
+## The shape in one picture
-
+
+
+
+
-[Open the PlantUML source](../assets/diagrams/sources/system-context.puml)
+The person never talks to rup-flow directly. They talk to an agent. The agent reads the
+rules of the skill, runs the CLI for the mechanical steps and writes the documents
+itself, because understanding a business is the part that needs a language model. Each
+side does what it is good at, and the boundary between them is a plain command line that
+any agent with a shell can use.
-## Parts
+## Principles
-| Part | Responsibility |
+| Principle | What it means in practice |
| --- | --- |
-| `SKILL.md` | The operating rules and the map from a request to the reference to read |
-| `references/` | Methodology, loaded on demand |
-| `templates/` | Starting content of each artifact, with `{{placeholders}}` |
-| `scripts/rup.mjs` | The CLI: structure, index, render, check, instructions |
-| `scripts/lib/` | Small modules: PlantUML client, use-case index, instruction blocks, edition loader |
-| `editions.json` | The catalogue of artifacts and capabilities, free or Pro |
-| `runtime/compose.yaml` | The PlantUML container definition |
-| `.claude-plugin/`, `install.mjs` | Adapters for Claude Code and for clients that read `.agents/skills` |
+| One portable core | The skill follows the open Agent Skills format. Anything specific to one agent lives in a small adapter and never in the skill |
+| The agent analyses, the CLI does the boilerplate | Structure, indexes, rendering and checks are deterministic code; judgement stays with the agent |
+| Honesty over completeness | The rules forbid inventing content, and the CLI refuses what an edition does not include instead of faking it |
+| Nothing to install | Node.js 18 or newer is enough; Docker only draws diagrams |
+| Two editions, one code base | The free CLI loads an extension when it finds one; there is no fork |
-## Principles
+## Where to read next
-- **One portable core.** The skill follows the Agent Skills format; client
- specifics live in adapters, never in the skill.
-- **The agent analyses, the CLI does the boilerplate.** Structure, index,
- rendering and checks are deterministic code.
-- **Honesty over completeness.** The rules forbid inventing content, and the CLI
- refuses what the edition does not include instead of faking it.
-- **No dependencies.** Node.js 18 or newer is enough.
+
-## In this section
+
-
+## Structure
+
+The system context, the runtime containers and the components inside the CLI.
+
+[Read the structure](structure.md)
+
+
+
+
+
+## Runtime behaviour
+
+What happens when the agent adds a use case, renders diagrams or starts the CLI.
+
+[Read the behaviour](behavior.md)
+
+
-### Editions and the extension point
+## Editions and the extension point
-How one CLI is both the free and the Pro edition.
+How one command line is both the free and the Pro edition.
-[Read more](editions.md)
+[Read about editions](editions.md)
-### Trust and data flow
+## Trust and data flow
What is read, what is written, what leaves your machine.
-[Read more](trust-and-data.md)
+[Read about trust](trust-and-data.md)
+
+
+
+
+
+## Quality and decisions
+
+The qualities the design protects, and the decisions behind it.
+
+[Read the decisions](decisions.md)
-### Delivery and branches
+## Delivery
-Releases, the plugin branch and the documentation site.
+Branches, releases and how this documentation is published.
-[Read more](delivery.md)
+[Read about delivery](delivery.md)
diff --git a/docs/architecture/structure.md b/docs/architecture/structure.md
new file mode 100644
index 0000000..ad3b0c3
--- /dev/null
+++ b/docs/architecture/structure.md
@@ -0,0 +1,72 @@
+---
+title: Structure
+description: The runtime containers of rup-flow and the components inside its command line.
+---
+
+# Structure
+
+## What runs where
+
+Everything runs on your machine. There are three runtime pieces and two stores.
+
+
+
+
+
+
+
+
+| Element | Responsibility |
+| --- | --- |
+| Agent process | Reads `SKILL.md` and the references, decides what to write, runs the CLI and writes the documents |
+| Node.js process | One short-lived run per CLI command: structure, index, render, check, instructions |
+| Skill folder | Rules, references, templates, the catalogue and the CLI itself; read-only at run time |
+| Project folder | `rup.config.json` and the documentation directory; the only place the tool writes |
+| PlantUML container | Turns diagram sources into SVG; published on `127.0.0.1` only and run with the `SANDBOX` security profile |
+
+The CLI is started fresh for every command and keeps no state between runs, except one
+small file in the documentation directory that records the last render so unchanged
+diagrams are skipped.
+
+## What is inside the skill folder
+
+| Path | Role |
+| --- | --- |
+| `SKILL.md` | The operating rules and the map from a request to the reference to read |
+| `references/` | Methodology, loaded on demand |
+| `templates/` | Starting content of each artifact, with `{{placeholders}}` |
+| `scripts/rup.mjs` | The CLI |
+| `scripts/lib/` | Small modules used by the CLI |
+| `editions.json` | The catalogue of artifacts and capabilities, free or Pro |
+| `runtime/compose.yaml` | The definition of the PlantUML container |
+
+## Inside the CLI
+
+
+
+
+
+
+
+
+| Component | Responsibility | Reason it is separate |
+| --- | --- | --- |
+| Argument parser | Splits a command line into the command, its arguments and flags | The only place that knows the shape of the command line |
+| Configuration loader | Merges defaults, `rup.config.json` and flags, in that order of precedence, and rejects values the edition does not support | Every command sees one resolved configuration |
+| Commands | One function per command | A command can change without touching the others |
+| `edition.mjs` | Detects the edition, loads the extension, prints Pro notices | The single point where the two editions differ |
+| `usecases.mjs` | Reads the use-case cards and builds the index and the navigation | Shared by `new use-case`, `index` and `check` |
+| `plantuml.mjs` | Sends a source to the server and checks that an SVG came back | The only code that speaks HTTP |
+| `instructions.mjs` | Writes the block that agents without skills read | Isolates the list of agent targets |
+| `scripts/pro` | Themes, Mermaid, explorer, use-case diagrams and code scan | Exists only in the Pro package |
+
+## Dependencies
+
+The CLI has no runtime dependencies. It uses the Node.js standard library, the global
+`fetch` for the PlantUML server and, only when asked, the `docker` command. Keeping the
+dependency list empty is a requirement, not an accident: it is what lets the skill be
+unzipped into any folder and run.
+
+## Related
+
+[Runtime behaviour](behavior.md) · [Editions and the extension point](editions.md)
diff --git a/docs/architecture/trust-and-data.md b/docs/architecture/trust-and-data.md
index 583ce2c..4598e23 100644
--- a/docs/architecture/trust-and-data.md
+++ b/docs/architecture/trust-and-data.md
@@ -5,7 +5,15 @@ description: What rup-flow reads and writes, what it sends over the network and
# Trust and data flow
-rup-flow has no account, no analytics and no remote service of its own.
+rup-flow has no account, no analytics and no service of its own. This page lists every
+boundary it touches.
+
+
+
+
+
+
+
## On your machine
@@ -15,28 +23,35 @@ rup-flow has no account, no analytics and no remote service of its own.
| Sends diagram sources | To the PlantUML server you run locally, `http://127.0.0.1:8085` by default |
| Pulls a container image | The PlantUML image from its public registry, the first time you start the server |
-Nothing else is sent anywhere.
+Nothing else is sent anywhere. rup-flow Pro adds one more image, the Mermaid renderer,
+pulled the first time you choose Mermaid.
## The agent
-The AI agent you use with the skill (Claude, Codex, Gemini or another) processes
-your prompts and files under that provider's terms and privacy policy, not
-rup-flow's.
+The AI agent you use with the skill processes your prompts and the files it reads under
+its provider's terms and privacy policy, not rup-flow's. rup-flow cannot see or limit that.
+Choose an agent whose terms fit the material you document.
## The PlantUML container
-The bundled compose file publishes the container on `127.0.0.1` only and runs it
-with `PLANTUML_SECURITY_PROFILE=SANDBOX`, which blocks file and address access
-from diagrams. Do not expose that port to a network without adding
-authentication.
+The bundled compose file publishes the container on `127.0.0.1` only and runs it with the
+`SANDBOX` security profile, which blocks file and address access from diagrams. Do not
+expose that port to a network without adding authentication. The CLI never uses an
+`!include` of a file or an address in the sources it writes.
+
+## Written output
+
+Generated documentation contains whatever you or the code contain. Review it before you
+publish it, especially output derived from code in rup-flow Pro: paths, configuration and
+table names.
-## Generated documentation
+## The explorer Pro
-It contains whatever you or the code contain. Review it before publishing it,
-especially output derived from code (paths, configuration, table names).
+`explorer.html` carries a content security policy that blocks every external load, and
+inserts diagrams and documents as nodes, never as raw HTML. It can be shared as a file.
## Reporting a vulnerability
-Use GitHub private vulnerability reporting on the
-[rup-flow repository](https://github.com/hector-ae21/rup-flow/security): do not
-open a public issue.
+Report vulnerabilities privately to the maintainer; do not open a public issue. The
+[security policy](https://github.com/hector-ae21/rup-flow-docs/blob/v0.x/SECURITY.md)
+explains where.
diff --git a/docs/assets/diagrams/catalogue/analysis-classes.svg b/docs/assets/diagrams/catalogue/analysis-classes.svg
deleted file mode 100644
index 9dac349..0000000
--- a/docs/assets/diagrams/catalogue/analysis-classes.svg
+++ /dev/null
@@ -1,229 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/collaboration.svg b/docs/assets/diagrams/catalogue/collaboration.svg
deleted file mode 100644
index 4d5d05d..0000000
--- a/docs/assets/diagrams/catalogue/collaboration.svg
+++ /dev/null
@@ -1,191 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/components.svg b/docs/assets/diagrams/catalogue/components.svg
deleted file mode 100644
index 2490024..0000000
--- a/docs/assets/diagrams/catalogue/components.svg
+++ /dev/null
@@ -1,87 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/data-model.svg b/docs/assets/diagrams/catalogue/data-model.svg
deleted file mode 100644
index 6196846..0000000
--- a/docs/assets/diagrams/catalogue/data-model.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/deployment.svg b/docs/assets/diagrams/catalogue/deployment.svg
deleted file mode 100644
index eac161f..0000000
--- a/docs/assets/diagrams/catalogue/deployment.svg
+++ /dev/null
@@ -1,13 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/design-classes.svg b/docs/assets/diagrams/catalogue/design-classes.svg
deleted file mode 100644
index e3ec8f3..0000000
--- a/docs/assets/diagrams/catalogue/design-classes.svg
+++ /dev/null
@@ -1,331 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/domain-model.svg b/docs/assets/diagrams/catalogue/domain-model.svg
deleted file mode 100644
index 3ecbd48..0000000
--- a/docs/assets/diagrams/catalogue/domain-model.svg
+++ /dev/null
@@ -1,97 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/entity-states.svg b/docs/assets/diagrams/catalogue/entity-states.svg
deleted file mode 100644
index 39e6247..0000000
--- a/docs/assets/diagrams/catalogue/entity-states.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/sequence.svg b/docs/assets/diagrams/catalogue/sequence.svg
deleted file mode 100644
index 479b46f..0000000
--- a/docs/assets/diagrams/catalogue/sequence.svg
+++ /dev/null
@@ -1,69 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/specification.svg b/docs/assets/diagrams/catalogue/specification.svg
deleted file mode 100644
index 12e015d..0000000
--- a/docs/assets/diagrams/catalogue/specification.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/use-case-overview.svg b/docs/assets/diagrams/catalogue/use-case-overview.svg
deleted file mode 100644
index b5a8e8f..0000000
--- a/docs/assets/diagrams/catalogue/use-case-overview.svg
+++ /dev/null
@@ -1,45 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/use-cases-customer.svg b/docs/assets/diagrams/catalogue/use-cases-customer.svg
deleted file mode 100644
index 4602fd1..0000000
--- a/docs/assets/diagrams/catalogue/use-cases-customer.svg
+++ /dev/null
@@ -1,23 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/dark/agent-compatibility.svg b/docs/assets/diagrams/dark/agent-compatibility.svg
new file mode 100644
index 0000000..f00d008
--- /dev/null
+++ b/docs/assets/diagrams/dark/agent-compatibility.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/dark/branch-model.svg b/docs/assets/diagrams/dark/branch-model.svg
new file mode 100644
index 0000000..b114f03
--- /dev/null
+++ b/docs/assets/diagrams/dark/branch-model.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/dark/cli-components.svg b/docs/assets/diagrams/dark/cli-components.svg
new file mode 100644
index 0000000..f1eeb31
--- /dev/null
+++ b/docs/assets/diagrams/dark/cli-components.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/dark/containers.svg b/docs/assets/diagrams/dark/containers.svg
new file mode 100644
index 0000000..093e051
--- /dev/null
+++ b/docs/assets/diagrams/dark/containers.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/dark/edition-loading.svg b/docs/assets/diagrams/dark/edition-loading.svg
new file mode 100644
index 0000000..10105c9
--- /dev/null
+++ b/docs/assets/diagrams/dark/edition-loading.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/dark/editions-overlay.svg b/docs/assets/diagrams/dark/editions-overlay.svg
new file mode 100644
index 0000000..db0090c
--- /dev/null
+++ b/docs/assets/diagrams/dark/editions-overlay.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/dark/new-use-case.svg b/docs/assets/diagrams/dark/new-use-case.svg
new file mode 100644
index 0000000..578aa5d
--- /dev/null
+++ b/docs/assets/diagrams/dark/new-use-case.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/dark/release-pipeline.svg b/docs/assets/diagrams/dark/release-pipeline.svg
new file mode 100644
index 0000000..b8fc91c
--- /dev/null
+++ b/docs/assets/diagrams/dark/release-pipeline.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/dark/render.svg b/docs/assets/diagrams/dark/render.svg
new file mode 100644
index 0000000..6403b61
--- /dev/null
+++ b/docs/assets/diagrams/dark/render.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/dark/system-context.svg b/docs/assets/diagrams/dark/system-context.svg
new file mode 100644
index 0000000..9bdd2ec
--- /dev/null
+++ b/docs/assets/diagrams/dark/system-context.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/dark/trust-boundaries.svg b/docs/assets/diagrams/dark/trust-boundaries.svg
new file mode 100644
index 0000000..6c04c1d
--- /dev/null
+++ b/docs/assets/diagrams/dark/trust-boundaries.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/editions-overlay.svg b/docs/assets/diagrams/editions-overlay.svg
deleted file mode 100644
index 0788818..0000000
--- a/docs/assets/diagrams/editions-overlay.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/diagrams/light/agent-compatibility.svg b/docs/assets/diagrams/light/agent-compatibility.svg
new file mode 100644
index 0000000..39a1f10
--- /dev/null
+++ b/docs/assets/diagrams/light/agent-compatibility.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/light/branch-model.svg b/docs/assets/diagrams/light/branch-model.svg
new file mode 100644
index 0000000..aded504
--- /dev/null
+++ b/docs/assets/diagrams/light/branch-model.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/light/cli-components.svg b/docs/assets/diagrams/light/cli-components.svg
new file mode 100644
index 0000000..523dbb7
--- /dev/null
+++ b/docs/assets/diagrams/light/cli-components.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/light/containers.svg b/docs/assets/diagrams/light/containers.svg
new file mode 100644
index 0000000..902449d
--- /dev/null
+++ b/docs/assets/diagrams/light/containers.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/light/edition-loading.svg b/docs/assets/diagrams/light/edition-loading.svg
new file mode 100644
index 0000000..1c9a3d6
--- /dev/null
+++ b/docs/assets/diagrams/light/edition-loading.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/light/editions-overlay.svg b/docs/assets/diagrams/light/editions-overlay.svg
new file mode 100644
index 0000000..515a212
--- /dev/null
+++ b/docs/assets/diagrams/light/editions-overlay.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/light/new-use-case.svg b/docs/assets/diagrams/light/new-use-case.svg
new file mode 100644
index 0000000..24767d1
--- /dev/null
+++ b/docs/assets/diagrams/light/new-use-case.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/light/release-pipeline.svg b/docs/assets/diagrams/light/release-pipeline.svg
new file mode 100644
index 0000000..2dc56c8
--- /dev/null
+++ b/docs/assets/diagrams/light/release-pipeline.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/light/render.svg b/docs/assets/diagrams/light/render.svg
new file mode 100644
index 0000000..6392ffe
--- /dev/null
+++ b/docs/assets/diagrams/light/render.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/light/system-context.svg b/docs/assets/diagrams/light/system-context.svg
new file mode 100644
index 0000000..8531d21
--- /dev/null
+++ b/docs/assets/diagrams/light/system-context.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/light/trust-boundaries.svg b/docs/assets/diagrams/light/trust-boundaries.svg
new file mode 100644
index 0000000..80f1e76
--- /dev/null
+++ b/docs/assets/diagrams/light/trust-boundaries.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/sources/_theme.iuml b/docs/assets/diagrams/sources/_theme.iuml
index d6e2faa..090e480 100644
--- a/docs/assets/diagrams/sources/_theme.iuml
+++ b/docs/assets/diagrams/sources/_theme.iuml
@@ -1,93 +1,131 @@
+!ifdef DARK
+!$text = "#E6EEFB"
+!$muted = "#B7C7E2"
+!$box = "#1E3A5F"
+!$boxAlt = "#2F5B94"
+!$border = "#8EC5FF"
+!$arrow = "#8EC5FF"
+!$package = "#122740"
+!$packageBorder = "#4F8FD6"
+!$accent = "#C9DDF2"
+!$note = "#17304F"
+!$noteBorder = "#C9DDF2"
+!else
+!$text = "#122740"
+!$muted = "#3D5F8C"
+!$box = "#EAF2FC"
+!$boxAlt = "#D3E4F8"
+!$border = "#4F8FD6"
+!$arrow = "#35609A"
+!$package = "#F5F8FC"
+!$packageBorder = "#8AAED6"
+!$accent = "#1E3A5F"
+!$note = "#FFF6DB"
+!$noteBorder = "#C9A646"
+!endif
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 12
skinparam defaultFontName Arial
-skinparam defaultFontColor #DDEBFF
-skinparam ArrowColor #8EC5FF
-skinparam ArrowFontColor #DDEBFF
-skinparam ArrowThickness 2
+skinparam defaultFontSize 13
+skinparam defaultFontColor $text
+skinparam ArrowColor $arrow
+skinparam ArrowFontColor $muted
+skinparam ArrowFontSize 12
+skinparam ArrowThickness 1.6
skinparam packageStyle rectangle
skinparam componentStyle rectangle
+skinparam nodesep 50
+skinparam ranksep 55
skinparam actor {
- BackgroundColor #1E3A5F
- BorderColor #4F8FD6
- FontColor #F8FAFC
+ BackgroundColor $box
+ BorderColor $border
+ FontColor $text
}
skinparam usecase {
- BackgroundColor #1E3A5F
- BorderColor #C9DDF2
- FontColor #F8FAFC
+ BackgroundColor $box
+ BorderColor $accent
+ FontColor $text
}
skinparam component {
- BackgroundColor #1E3A5F
- BorderColor #4F8FD6
- FontColor #F8FAFC
+ BackgroundColor $box
+ BorderColor $border
+ FontColor $text
}
skinparam rectangle {
- BackgroundColor #1E3A5F
- BorderColor #4F8FD6
- FontColor #F8FAFC
+ BackgroundColor $box
+ BorderColor $border
+ FontColor $text
}
skinparam package {
- BackgroundColor #122740
- BorderColor #C9DDF2
- FontColor #F8FAFC
+ BackgroundColor $package
+ BorderColor $packageBorder
+ FontColor $text
+}
+skinparam node {
+ BackgroundColor $box
+ BorderColor $border
+ FontColor $text
}
skinparam cloud {
- BackgroundColor #2F5B94
- BorderColor #8EC5FF
- FontColor #F8FAFC
+ BackgroundColor $boxAlt
+ BorderColor $border
+ FontColor $text
}
skinparam database {
- BackgroundColor #2F5B94
- BorderColor #8EC5FF
- FontColor #F8FAFC
+ BackgroundColor $boxAlt
+ BorderColor $border
+ FontColor $text
}
skinparam file {
- BackgroundColor #1E3A5F
- BorderColor #C9DDF2
- FontColor #F8FAFC
+ BackgroundColor $box
+ BorderColor $accent
+ FontColor $text
}
skinparam class {
- BackgroundColor #1E3A5F
- BorderColor #4F8FD6
- HeaderBackgroundColor #2F5B94
- FontColor #F8FAFC
- AttributeFontColor #DDEBFF
+ BackgroundColor $box
+ BorderColor $border
+ HeaderBackgroundColor $boxAlt
+ FontColor $text
+ AttributeFontColor $text
}
skinparam sequence {
- ActorBackgroundColor #1E3A5F
- ActorBorderColor #4F8FD6
- ActorFontColor #F8FAFC
- LifeLineBorderColor #8EC5FF
- LifeLineBackgroundColor #1E3A5F
- ParticipantBackgroundColor #1E3A5F
- ParticipantBorderColor #4F8FD6
- ParticipantFontColor #F8FAFC
- GroupBackgroundColor #122740
- GroupBorderColor #C9DDF2
- GroupFontColor #F8FAFC
+ ActorBackgroundColor $box
+ ActorBorderColor $border
+ ActorFontColor $text
+ LifeLineBorderColor $arrow
+ LifeLineBackgroundColor $box
+ ParticipantBackgroundColor $box
+ ParticipantBorderColor $border
+ ParticipantFontColor $text
+ GroupBackgroundColor $package
+ GroupBorderColor $packageBorder
+ GroupFontColor $text
+ BoxBackgroundColor $package
+ BoxBorderColor $packageBorder
}
skinparam activity {
- BackgroundColor #1E3A5F
- BorderColor #4F8FD6
- FontColor #F8FAFC
- DiamondBackgroundColor #2F5B94
- DiamondBorderColor #C9DDF2
- DiamondFontColor #F8FAFC
- StartColor #8EC5FF
- EndColor #C9DDF2
- BarColor #8EC5FF
+ BackgroundColor $box
+ BorderColor $border
+ FontColor $text
+ DiamondBackgroundColor $boxAlt
+ DiamondBorderColor $accent
+ DiamondFontColor $text
+ StartColor $arrow
+ EndColor $accent
+ BarColor $arrow
}
skinparam note {
- BackgroundColor #17304F
- BorderColor #C9DDF2
- FontColor #F8FAFC
+ BackgroundColor $note
+ BorderColor $noteBorder
+ FontColor $text
}
skinparam state {
- BackgroundColor #1E3A5F
- BorderColor #4F8FD6
- FontColor #F8FAFC
- StartColor #8EC5FF
- EndColor #C9DDF2
+ BackgroundColor $box
+ BorderColor $border
+ FontColor $text
+ StartColor $arrow
+ EndColor $accent
}
+skinparam ActivityStartColor $arrow
+skinparam ActivityEndColor $accent
diff --git a/docs/assets/diagrams/sources/agent-compatibility.puml b/docs/assets/diagrams/sources/agent-compatibility.puml
new file mode 100644
index 0000000..1e903b5
--- /dev/null
+++ b/docs/assets/diagrams/sources/agent-compatibility.puml
@@ -0,0 +1,17 @@
+@startuml agent-compatibility
+!include _theme.iuml
+
+rectangle "Reads Agent Skills\nClaude Code, Claude web, Codex,\nGemini CLI and others" as Skills
+rectangle "Reads an instruction file\nCursor, Copilot, Windsurf, Cline,\nRoo, Kilo, Continue, Junie,\nAmazon Q, Zed, Aider" as Files
+rectangle "Any other agent\nwith a shell" as Other
+
+rectangle "Skill folder\n.claude/skills or .agents/skills" as Folder
+rectangle "Instruction block\nwritten by rup.mjs instructions" as Block
+rectangle "CLI\nrup.mjs" as CLI
+
+Skills --> Folder : loads on demand
+Files --> Block : reads
+Other --> Block : portable file RUP-FLOW.md
+Block --> Folder : points to
+Folder --> CLI : scripts/rup.mjs
+@enduml
diff --git a/docs/assets/diagrams/sources/branch-model.puml b/docs/assets/diagrams/sources/branch-model.puml
new file mode 100644
index 0000000..7fb3157
--- /dev/null
+++ b/docs/assets/diagrams/sources/branch-model.puml
@@ -0,0 +1,22 @@
+@startuml branch-model
+!include _theme.iuml
+
+rectangle "Private repository" as Repo {
+ rectangle "main\nfree edition" as Main
+ rectangle "pro\nmain plus the pro/ folder" as Pro
+}
+
+rectangle "Tag vX.Y.Z" as FreeTag
+rectangle "Tag pro-vX.Y.Z" as ProTag
+rectangle "rup-flow-free-X.Y.Z.zip" as FreeZip
+rectangle "rup-flow-pro-X.Y.Z.zip" as ProZip
+rectangle "Documentation site\npublic repository" as Docs
+
+Main --> Pro : merge main into pro
+Main --> FreeTag
+Pro --> ProTag
+FreeTag --> FreeZip : release workflow
+ProTag --> ProZip : release workflow
+FreeZip --> Docs : described, never published as source
+ProZip --> Docs : described at feature level
+@enduml
diff --git a/docs/assets/diagrams/sources/cli-components.puml b/docs/assets/diagrams/sources/cli-components.puml
new file mode 100644
index 0000000..fa5e0c4
--- /dev/null
+++ b/docs/assets/diagrams/sources/cli-components.puml
@@ -0,0 +1,29 @@
+@startuml cli-components
+!include _theme.iuml
+
+package "scripts/rup.mjs" as Main {
+ rectangle "Argument parser" as Args
+ rectangle "Configuration loader\ndefaults, file, flags" as Config
+ rectangle "Commands\ninit, new, index, render, check,\neditions, version, instructions, server" as Commands
+}
+
+package "scripts/lib" as Lib {
+ rectangle "edition.mjs\nedition loader and Pro notices" as Edition
+ rectangle "usecases.mjs\ncards, index, navigation" as UseCases
+ rectangle "plantuml.mjs\nserver client" as Client
+ rectangle "instructions.mjs\nagent instruction blocks" as Instructions
+}
+
+package "scripts/pro (Pro only)" as Pro {
+ rectangle "themes, mermaid, explorer,\nuse-case diagrams, scan" as Extension
+}
+
+Args --> Config
+Config --> Commands
+Commands --> Edition
+Commands --> UseCases
+Commands --> Client
+Commands --> Instructions
+Edition ..> Extension : loads when\nscripts/pro/index.mjs exists
+Commands ..> Extension : calls its hooks
+@enduml
diff --git a/docs/assets/diagrams/sources/containers.puml b/docs/assets/diagrams/sources/containers.puml
new file mode 100644
index 0000000..9601925
--- /dev/null
+++ b/docs/assets/diagrams/sources/containers.puml
@@ -0,0 +1,24 @@
+@startuml containers
+!include _theme.iuml
+
+rectangle "Your machine" as Machine {
+ rectangle "Agent process\nreads SKILL.md, calls the CLI" as Agent
+ rectangle "Node.js process\nrup.mjs, one run per command" as Node
+ database "Skill folder\nSKILL.md, references, templates, editions.json" as SkillDir
+ database "Project folder\nrup.config.json and docs/rup" as Project
+ rectangle "Docker container\nPlantUML server on 127.0.0.1:8085" as Docker
+}
+
+Agent --> SkillDir : reads
+Agent --> Node : shell command
+Node --> SkillDir : templates, catalogue
+Node --> Project : reads and writes
+Node --> Docker : HTTP, diagram source
+Docker --> Node : SVG
+Agent --> Project : writes documents
+
+note bottom of Docker
+ Published on the loopback interface only,
+ with the SANDBOX security profile.
+end note
+@enduml
diff --git a/docs/assets/diagrams/sources/edition-loading.puml b/docs/assets/diagrams/sources/edition-loading.puml
new file mode 100644
index 0000000..c8fe81a
--- /dev/null
+++ b/docs/assets/diagrams/sources/edition-loading.puml
@@ -0,0 +1,20 @@
+@startuml edition-loading
+!include _theme.iuml
+
+start
+:CLI starts;
+if (scripts/pro/index.mjs exists?) then (yes)
+ :Load the Pro extension;
+ :Pro edition: all templates,\nthemes, Mermaid, explorer, scan;
+else (no)
+ :Free edition;
+ if (command or flag needs Pro?) then (yes)
+ :Stop with the Pro notice,\nexit code 1;
+ stop
+ else (no)
+ :Run;
+ endif
+endif
+:Write the report;
+stop
+@enduml
diff --git a/docs/assets/diagrams/sources/editions-overlay.puml b/docs/assets/diagrams/sources/editions-overlay.puml
index 91100ae..cfb157c 100644
--- a/docs/assets/diagrams/sources/editions-overlay.puml
+++ b/docs/assets/diagrams/sources/editions-overlay.puml
@@ -1,31 +1,28 @@
@startuml editions-overlay
!include _theme.iuml
-left to right direction
-package "rup-flow (free, public, MIT)" as Free {
- rectangle "SKILL.md, references, templates\nFree workflow" as FreeSkill
- rectangle "CLI\nLoads an extension when present" as FreeCli
- rectangle "editions.json\nCatalogue" as Catalogue
+package "main branch" as Free {
+ rectangle "SKILL.md, references, templates\nthe free workflow" as FreeSkill
+ rectangle "CLI\nloads an extension when present" as FreeCli
+ rectangle "editions.json\nthe catalogue" as Catalogue
}
-package "Pro overlay (private)" as Pro {
- rectangle "scripts/pro\nThemes, Mermaid, explorer, scan" as Extension
- rectangle "Templates and references\nThe full workflow" as ProTemplates
+package "pro branch: pro/overlay" as Pro {
+ rectangle "scripts/pro\nthemes, Mermaid, explorer,\nuse-case diagrams, scan" as Extension
+ rectangle "Templates and references\nthe full workflow" as ProTemplates
rectangle "Packs, domain libraries\nand subagents" as Extras
}
-rectangle "rup-flow-pro package\nOne skill, both sets" as Package
+rectangle "rup-flow-pro package\none skill, both sets" as Package
+rectangle "rup-flow-free package" as FreePackage
+FreeSkill --> FreePackage : zip
+FreeCli --> FreePackage : zip
+Catalogue --> FreePackage : zip
FreeSkill --> Package : copied
FreeCli --> Package : copied
Catalogue --> Package : copied
Extension --> Package : laid over
ProTemplates --> Package : laid over
Extras --> Package : added
-Package ..> FreeCli : scripts/pro/index.mjs found:\nPro behaviour
-
-note bottom of Free
- Without the extension the same CLI
- runs as the free edition.
-end note
@enduml
diff --git a/docs/assets/diagrams/sources/new-use-case.puml b/docs/assets/diagrams/sources/new-use-case.puml
new file mode 100644
index 0000000..ee02329
--- /dev/null
+++ b/docs/assets/diagrams/sources/new-use-case.puml
@@ -0,0 +1,22 @@
+@startuml new-use-case
+!include _theme.iuml
+skinparam sequenceMessageAlign center
+
+actor "Person" as Person
+participant "Agent" as Agent
+participant "CLI" as CLI
+database "Templates" as Templates
+database "Project" as Project
+
+Person -> Agent : "Add the use case cancelOrder"
+Agent -> CLI : new use-case cancelOrder --actor Customer
+CLI -> Project : next free identifier (UC-xxx)
+CLI -> Templates : card and specification
+CLI -> Project : write the files that do not exist yet
+CLI -> Project : refresh the use-case index
+CLI --> Agent : report: created, skipped, index
+Agent -> Project : fill the card from what the person said
+Agent -> CLI : check
+CLI --> Agent : errors and warnings
+Agent --> Person : files, open questions, what was not checked
+@enduml
diff --git a/docs/assets/diagrams/sources/release-pipeline.puml b/docs/assets/diagrams/sources/release-pipeline.puml
new file mode 100644
index 0000000..6c495a3
--- /dev/null
+++ b/docs/assets/diagrams/sources/release-pipeline.puml
@@ -0,0 +1,18 @@
+@startuml release-pipeline
+!include _theme.iuml
+
+rectangle "Pull request" as PR
+rectangle "CI\nvalidate, test,\nrender" as CI
+rectangle "Merge" as Merge
+rectangle "Tag" as Tag
+rectangle "Release workflow\ncheck, build, package" as Release
+rectangle "GitHub release\nwith the versioned ZIP" as Asset
+rectangle "Marketplace listing\nand direct buyers" as Market
+
+PR --> CI
+CI --> Merge : CI complete
+Merge --> Tag : version bumped,\nchangelog written
+Tag --> Release
+Release --> Asset
+Asset --> Market : uploaded by hand
+@enduml
diff --git a/docs/assets/diagrams/sources/render.puml b/docs/assets/diagrams/sources/render.puml
new file mode 100644
index 0000000..8b41d5c
--- /dev/null
+++ b/docs/assets/diagrams/sources/render.puml
@@ -0,0 +1,22 @@
+@startuml render
+!include _theme.iuml
+skinparam sequenceMessageAlign center
+
+participant "CLI" as CLI
+participant "Project" as Project
+participant "PlantUML server" as Server
+
+CLI -> Project : find every .puml source
+loop each diagram not up to date
+ CLI -> Server : POST /svg with the source
+ alt syntax error or server down
+ Server --> CLI : error
+ CLI -> CLI : add to the failed list
+ else drawn
+ Server --> CLI : SVG
+ CLI -> Project : write name.svg next to the source
+ end
+end
+CLI -> Project : record the render state
+CLI --> CLI : exit 1 if anything failed
+@enduml
diff --git a/docs/assets/diagrams/sources/system-context.puml b/docs/assets/diagrams/sources/system-context.puml
index ab98a84..38836ce 100644
--- a/docs/assets/diagrams/sources/system-context.puml
+++ b/docs/assets/diagrams/sources/system-context.puml
@@ -1,26 +1,25 @@
@startuml system-context
!include _theme.iuml
-left to right direction
actor "Developer or analyst" as Person
-rectangle "AI coding agent\nClaude Code, Claude on the web, Codex, Gemini CLI" as Agent
-rectangle "rup-flow skill" as Skill {
- rectangle "SKILL.md and references\nRules and methodology, loaded on demand" as Rules
- rectangle "CLI (rup.mjs)\ninit, new use-case, index, render, check" as CLI
- rectangle "Templates and editions catalogue" as Templates
+rectangle "AI coding agent\nClaude, Codex, Gemini, Cursor, Copilot and others" as Agent
+
+package "rup-flow" as Skill {
+ rectangle "Skill\nSKILL.md and references" as Rules
+ rectangle "CLI\nrup.mjs" as CLI
+ rectangle "Templates and catalogue" as Templates
}
-database "The documentation folder and\nthe configuration file" as Files
-rectangle "PlantUML server\nLocal Docker container, 127.0.0.1" as PlantUML
+database "Project\nrup.config.json and the documentation folder" as Files
+rectangle "PlantUML server\nlocal Docker container" as PlantUML
-Person --> Agent : prompt
-Agent --> Rules : reads
-Agent --> CLI : runs
+Person --> Agent : asks in plain language
+Agent --> Rules : reads the rules
+Agent --> CLI : runs commands
CLI --> Templates : fills
CLI --> Files : reads and writes
CLI --> PlantUML : diagram sources
PlantUML --> CLI : SVG
-Agent --> Files : writes documents
-Agent --> Person : report: created, open questions, unchecked
+Agent --> Person : report of what was done,\nopen questions, unchecked items
@enduml
diff --git a/docs/assets/diagrams/sources/trust-boundaries.puml b/docs/assets/diagrams/sources/trust-boundaries.puml
new file mode 100644
index 0000000..ae698ff
--- /dev/null
+++ b/docs/assets/diagrams/sources/trust-boundaries.puml
@@ -0,0 +1,23 @@
+@startuml trust-boundaries
+!include _theme.iuml
+left to right direction
+
+package "Your machine" as Local {
+ rectangle "rup-flow CLI" as CLI
+ database "Project files" as Files
+ rectangle "PlantUML container\n127.0.0.1 only" as PlantUML
+}
+
+cloud "Agent provider\nits own terms and privacy policy" as Provider
+cloud "Container registry\nimage pulled once" as Registry
+
+CLI --> Files : reads and writes\ninside the folders you choose
+CLI --> PlantUML : diagram sources
+Provider ..> Files : prompts and files the agent reads
+Registry ..> PlantUML : first start only
+
+note bottom of Local
+ rup-flow has no account, no analytics
+ and no service of its own.
+end note
+@enduml
diff --git a/docs/assets/diagrams/system-context.svg b/docs/assets/diagrams/system-context.svg
deleted file mode 100644
index a8b447c..0000000
--- a/docs/assets/diagrams/system-context.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/explorer/explorer-overview.png b/docs/assets/explorer/explorer-overview.png
deleted file mode 100644
index bde6e9f..0000000
Binary files a/docs/assets/explorer/explorer-overview.png and /dev/null differ
diff --git a/docs/assets/explorer/overview-dark.png b/docs/assets/explorer/overview-dark.png
new file mode 100644
index 0000000..ccca3dd
Binary files /dev/null and b/docs/assets/explorer/overview-dark.png differ
diff --git a/docs/assets/explorer/overview-light.png b/docs/assets/explorer/overview-light.png
new file mode 100644
index 0000000..57c5435
Binary files /dev/null and b/docs/assets/explorer/overview-light.png differ
diff --git a/docs/assets/explorer/trace-dark.png b/docs/assets/explorer/trace-dark.png
new file mode 100644
index 0000000..14cab04
Binary files /dev/null and b/docs/assets/explorer/trace-dark.png differ
diff --git a/docs/assets/explorer/trace-light.png b/docs/assets/explorer/trace-light.png
new file mode 100644
index 0000000..921e7a1
Binary files /dev/null and b/docs/assets/explorer/trace-light.png differ
diff --git a/docs/assets/gallery/dark/analysis-classes.svg b/docs/assets/gallery/dark/analysis-classes.svg
new file mode 100644
index 0000000..c818968
--- /dev/null
+++ b/docs/assets/gallery/dark/analysis-classes.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/collaboration.svg b/docs/assets/gallery/dark/collaboration.svg
new file mode 100644
index 0000000..16425ec
--- /dev/null
+++ b/docs/assets/gallery/dark/collaboration.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/components.svg b/docs/assets/gallery/dark/components.svg
new file mode 100644
index 0000000..e714f4c
--- /dev/null
+++ b/docs/assets/gallery/dark/components.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/data-model.svg b/docs/assets/gallery/dark/data-model.svg
new file mode 100644
index 0000000..b69d705
--- /dev/null
+++ b/docs/assets/gallery/dark/data-model.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/deployment.svg b/docs/assets/gallery/dark/deployment.svg
new file mode 100644
index 0000000..69d0961
--- /dev/null
+++ b/docs/assets/gallery/dark/deployment.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/design-classes.svg b/docs/assets/gallery/dark/design-classes.svg
new file mode 100644
index 0000000..dd2b7c1
--- /dev/null
+++ b/docs/assets/gallery/dark/design-classes.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/domain-model-simple.svg b/docs/assets/gallery/dark/domain-model-simple.svg
new file mode 100644
index 0000000..85428af
--- /dev/null
+++ b/docs/assets/gallery/dark/domain-model-simple.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/domain-model.svg b/docs/assets/gallery/dark/domain-model.svg
new file mode 100644
index 0000000..a58acca
--- /dev/null
+++ b/docs/assets/gallery/dark/domain-model.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/entity-states.svg b/docs/assets/gallery/dark/entity-states.svg
new file mode 100644
index 0000000..406aed7
--- /dev/null
+++ b/docs/assets/gallery/dark/entity-states.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/sequence.svg b/docs/assets/gallery/dark/sequence.svg
new file mode 100644
index 0000000..551dde4
--- /dev/null
+++ b/docs/assets/gallery/dark/sequence.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/specification.svg b/docs/assets/gallery/dark/specification.svg
new file mode 100644
index 0000000..27db010
--- /dev/null
+++ b/docs/assets/gallery/dark/specification.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/use-case-overview.svg b/docs/assets/gallery/dark/use-case-overview.svg
new file mode 100644
index 0000000..878939b
--- /dev/null
+++ b/docs/assets/gallery/dark/use-case-overview.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/dark/use-cases-customer.svg b/docs/assets/gallery/dark/use-cases-customer.svg
new file mode 100644
index 0000000..02b4d86
--- /dev/null
+++ b/docs/assets/gallery/dark/use-cases-customer.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/wireframes.svg b/docs/assets/gallery/dark/wireframes.svg
similarity index 93%
rename from docs/assets/diagrams/catalogue/wireframes.svg
rename to docs/assets/gallery/dark/wireframes.svg
index 79abef6..2a863a2 100644
--- a/docs/assets/diagrams/catalogue/wireframes.svg
+++ b/docs/assets/gallery/dark/wireframes.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/analysis-classes.svg b/docs/assets/gallery/light/analysis-classes.svg
new file mode 100644
index 0000000..e8d48a9
--- /dev/null
+++ b/docs/assets/gallery/light/analysis-classes.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/collaboration.svg b/docs/assets/gallery/light/collaboration.svg
new file mode 100644
index 0000000..da86c1d
--- /dev/null
+++ b/docs/assets/gallery/light/collaboration.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/components.svg b/docs/assets/gallery/light/components.svg
new file mode 100644
index 0000000..a9c5a91
--- /dev/null
+++ b/docs/assets/gallery/light/components.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/data-model.svg b/docs/assets/gallery/light/data-model.svg
new file mode 100644
index 0000000..251ac8e
--- /dev/null
+++ b/docs/assets/gallery/light/data-model.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/deployment.svg b/docs/assets/gallery/light/deployment.svg
new file mode 100644
index 0000000..926252b
--- /dev/null
+++ b/docs/assets/gallery/light/deployment.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/design-classes.svg b/docs/assets/gallery/light/design-classes.svg
new file mode 100644
index 0000000..27710b0
--- /dev/null
+++ b/docs/assets/gallery/light/design-classes.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/diagrams/catalogue/domain-model-simple.svg b/docs/assets/gallery/light/domain-model-simple.svg
similarity index 66%
rename from docs/assets/diagrams/catalogue/domain-model-simple.svg
rename to docs/assets/gallery/light/domain-model-simple.svg
index dcd4968..9d190cd 100644
--- a/docs/assets/diagrams/catalogue/domain-model-simple.svg
+++ b/docs/assets/gallery/light/domain-model-simple.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/domain-model.svg b/docs/assets/gallery/light/domain-model.svg
new file mode 100644
index 0000000..c16e7c5
--- /dev/null
+++ b/docs/assets/gallery/light/domain-model.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/entity-states.svg b/docs/assets/gallery/light/entity-states.svg
new file mode 100644
index 0000000..8237b6f
--- /dev/null
+++ b/docs/assets/gallery/light/entity-states.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/sequence.svg b/docs/assets/gallery/light/sequence.svg
new file mode 100644
index 0000000..382b114
--- /dev/null
+++ b/docs/assets/gallery/light/sequence.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/specification.svg b/docs/assets/gallery/light/specification.svg
new file mode 100644
index 0000000..6a691e3
--- /dev/null
+++ b/docs/assets/gallery/light/specification.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/use-case-overview.svg b/docs/assets/gallery/light/use-case-overview.svg
new file mode 100644
index 0000000..95999b9
--- /dev/null
+++ b/docs/assets/gallery/light/use-case-overview.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/use-cases-customer.svg b/docs/assets/gallery/light/use-cases-customer.svg
new file mode 100644
index 0000000..d79b11f
--- /dev/null
+++ b/docs/assets/gallery/light/use-cases-customer.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/light/wireframes.svg b/docs/assets/gallery/light/wireframes.svg
new file mode 100644
index 0000000..2a863a2
--- /dev/null
+++ b/docs/assets/gallery/light/wireframes.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/themes/dark.svg b/docs/assets/gallery/themes/dark.svg
new file mode 100644
index 0000000..a58acca
--- /dev/null
+++ b/docs/assets/gallery/themes/dark.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/themes/default.svg b/docs/assets/gallery/themes/default.svg
new file mode 100644
index 0000000..c16e7c5
--- /dev/null
+++ b/docs/assets/gallery/themes/default.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/themes/forest.svg b/docs/assets/gallery/themes/forest.svg
new file mode 100644
index 0000000..e9470ba
--- /dev/null
+++ b/docs/assets/gallery/themes/forest.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/themes/grape.svg b/docs/assets/gallery/themes/grape.svg
new file mode 100644
index 0000000..171c8d8
--- /dev/null
+++ b/docs/assets/gallery/themes/grape.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/themes/high-contrast.svg b/docs/assets/gallery/themes/high-contrast.svg
new file mode 100644
index 0000000..dc1359f
--- /dev/null
+++ b/docs/assets/gallery/themes/high-contrast.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/themes/mono.svg b/docs/assets/gallery/themes/mono.svg
new file mode 100644
index 0000000..6cde97b
--- /dev/null
+++ b/docs/assets/gallery/themes/mono.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/themes/ocean.svg b/docs/assets/gallery/themes/ocean.svg
new file mode 100644
index 0000000..e57ff65
--- /dev/null
+++ b/docs/assets/gallery/themes/ocean.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/gallery/themes/sunset.svg b/docs/assets/gallery/themes/sunset.svg
new file mode 100644
index 0000000..c165c8e
--- /dev/null
+++ b/docs/assets/gallery/themes/sunset.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/assets/mermaid/collaboration.svg b/docs/assets/mermaid/collaboration.svg
deleted file mode 100644
index 47fe729..0000000
--- a/docs/assets/mermaid/collaboration.svg
+++ /dev/null
@@ -1,1049 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/mermaid/components.svg b/docs/assets/mermaid/components.svg
deleted file mode 100644
index 98e7864..0000000
--- a/docs/assets/mermaid/components.svg
+++ /dev/null
@@ -1,119 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/mermaid/data-model.svg b/docs/assets/mermaid/data-model.svg
deleted file mode 100644
index 5ac93fe..0000000
--- a/docs/assets/mermaid/data-model.svg
+++ /dev/null
@@ -1,951 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/mermaid/deployment.svg b/docs/assets/mermaid/deployment.svg
deleted file mode 100644
index 7907240..0000000
--- a/docs/assets/mermaid/deployment.svg
+++ /dev/null
@@ -1,1095 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/mermaid/domain-model-forest.svg b/docs/assets/mermaid/domain-model-forest.svg
deleted file mode 100644
index cd54b09..0000000
--- a/docs/assets/mermaid/domain-model-forest.svg
+++ /dev/null
@@ -1,231 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/mermaid/domain-model.svg b/docs/assets/mermaid/domain-model.svg
deleted file mode 100644
index eedd09f..0000000
--- a/docs/assets/mermaid/domain-model.svg
+++ /dev/null
@@ -1,231 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/mermaid/sequence-dark.svg b/docs/assets/mermaid/sequence-dark.svg
deleted file mode 100644
index 48977c5..0000000
--- a/docs/assets/mermaid/sequence-dark.svg
+++ /dev/null
@@ -1,91 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/mermaid/sequence.svg b/docs/assets/mermaid/sequence.svg
deleted file mode 100644
index 99da1e3..0000000
--- a/docs/assets/mermaid/sequence.svg
+++ /dev/null
@@ -1,91 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/mermaid/specification.svg b/docs/assets/mermaid/specification.svg
deleted file mode 100644
index f838fea..0000000
--- a/docs/assets/mermaid/specification.svg
+++ /dev/null
@@ -1,387 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/mermaid/use-case-overview.svg b/docs/assets/mermaid/use-case-overview.svg
deleted file mode 100644
index 57a6678..0000000
--- a/docs/assets/mermaid/use-case-overview.svg
+++ /dev/null
@@ -1,2073 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/stylesheets/extra.css b/docs/assets/stylesheets/extra.css
index 7c4d7ea..1cd0c6f 100644
--- a/docs/assets/stylesheets/extra.css
+++ b/docs/assets/stylesheets/extra.css
@@ -768,3 +768,133 @@
margin-top: 0.7rem;
text-align: center;
}
+
+/* Edition marks: Pro is amber on purpose, so it never reads as a link or as the brand blue. */
+:root {
+ --rup-pro-fg: #8a4b00;
+ --rup-pro-bg: #fff3d6;
+ --rup-pro-border: #e0a43a;
+ --rup-free-fg: #1d5c3a;
+ --rup-free-bg: #e2f5ea;
+ --rup-free-border: #6dbb8f;
+ --md-admonition-icon--pro: url('data:image/svg+xml;charset=utf-8,');
+}
+
+[data-md-color-scheme="slate"] {
+ --rup-pro-fg: #ffd27a;
+ --rup-pro-bg: #3b2a08;
+ --rup-pro-border: #a8741c;
+ --rup-free-fg: #9be3b8;
+ --rup-free-bg: #0f3321;
+ --rup-free-border: #3c8a60;
+}
+
+.rup-pro-tag,
+.rup-free-tag {
+ border: 0.05rem solid var(--rup-pro-border);
+ border-radius: 999px;
+ display: inline-block;
+ font-size: 0.62rem;
+ font-weight: 800;
+ letter-spacing: 0.08em;
+ line-height: 1.5;
+ padding: 0.05rem 0.5rem;
+ text-transform: uppercase;
+ vertical-align: middle;
+}
+
+.rup-pro-tag {
+ background: var(--rup-pro-bg);
+ color: var(--rup-pro-fg);
+}
+
+.rup-free-tag {
+ background: var(--rup-free-bg);
+ border-color: var(--rup-free-border);
+ color: var(--rup-free-fg);
+}
+
+.rup-pro-tag--nav {
+ font-size: 0.5rem;
+ margin-left: 0.4rem;
+ padding: 0 0.35rem;
+}
+
+.rup-edition-banner {
+ align-items: center;
+ background: var(--rup-pro-bg);
+ border: 0.05rem solid var(--rup-pro-border);
+ border-left-width: 0.3rem;
+ border-radius: 0.5rem;
+ color: var(--md-default-fg-color);
+ display: flex;
+ flex-wrap: wrap;
+ gap: 0.6rem;
+ margin: 0 0 1.4rem;
+ padding: 0.6rem 0.9rem;
+}
+
+.rup-edition-banner .rup-pro-tag {
+ background: var(--rup-pro-fg);
+ border-color: var(--rup-pro-fg);
+ color: var(--rup-pro-bg);
+}
+
+.md-typeset .admonition.pro,
+.md-typeset details.pro {
+ border-color: var(--rup-pro-border);
+}
+
+.md-typeset .pro > .admonition-title,
+.md-typeset .pro > summary {
+ background-color: var(--rup-pro-bg);
+}
+
+.md-typeset .pro > .admonition-title::before,
+.md-typeset .pro > summary::before {
+ background-color: var(--rup-pro-fg);
+ -webkit-mask-image: var(--md-admonition-icon--pro);
+ mask-image: var(--md-admonition-icon--pro);
+}
+
+.md-typeset table:not([class]) td .rup-pro-tag,
+.md-typeset table:not([class]) td .rup-free-tag {
+ white-space: nowrap;
+}
+
+/* Diagrams follow the page theme: one light and one dark SVG per diagram. */
+.rup-diagram {
+ background: var(--rup-panel);
+ border: 0.05rem solid var(--rup-border);
+}
+
+.rup-gallery figure {
+ background: var(--rup-panel);
+}
+
+.rup-gallery figcaption {
+ color: var(--md-default-fg-color--light);
+}
+
+.rup-diagram--light {
+ background: var(--rup-panel);
+ border-color: var(--rup-border);
+}
+
+.rup-diagram img {
+ height: auto;
+ max-width: 100%;
+ min-width: 0;
+}
+
+@media screen and (max-width: 44.9375em) {
+ .rup-diagram img {
+ max-width: none;
+ min-width: 34rem;
+ }
+}
+
+.rup-edition-banner {
+ align-items: baseline;
+ flex-wrap: nowrap;
+}
diff --git a/docs/assets/themes/custom.svg b/docs/assets/themes/custom.svg
deleted file mode 100644
index c3389e4..0000000
--- a/docs/assets/themes/custom.svg
+++ /dev/null
@@ -1,97 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/themes/dark.svg b/docs/assets/themes/dark.svg
deleted file mode 100644
index 2518b38..0000000
--- a/docs/assets/themes/dark.svg
+++ /dev/null
@@ -1,97 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/themes/default.svg b/docs/assets/themes/default.svg
deleted file mode 100644
index 3ecbd48..0000000
--- a/docs/assets/themes/default.svg
+++ /dev/null
@@ -1,97 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/themes/forest.svg b/docs/assets/themes/forest.svg
deleted file mode 100644
index 18ddeb0..0000000
--- a/docs/assets/themes/forest.svg
+++ /dev/null
@@ -1,97 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/themes/grape.svg b/docs/assets/themes/grape.svg
deleted file mode 100644
index a54b230..0000000
--- a/docs/assets/themes/grape.svg
+++ /dev/null
@@ -1,97 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/themes/high-contrast.svg b/docs/assets/themes/high-contrast.svg
deleted file mode 100644
index d5ce81a..0000000
--- a/docs/assets/themes/high-contrast.svg
+++ /dev/null
@@ -1,97 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/themes/mono.svg b/docs/assets/themes/mono.svg
deleted file mode 100644
index 37c282b..0000000
--- a/docs/assets/themes/mono.svg
+++ /dev/null
@@ -1,97 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/themes/ocean.svg b/docs/assets/themes/ocean.svg
deleted file mode 100644
index d85996e..0000000
--- a/docs/assets/themes/ocean.svg
+++ /dev/null
@@ -1,97 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/assets/themes/overview.svg b/docs/assets/themes/overview.svg
deleted file mode 100644
index aa131a6..0000000
--- a/docs/assets/themes/overview.svg
+++ /dev/null
@@ -1,107 +0,0 @@
-
diff --git a/docs/assets/themes/sunset.svg b/docs/assets/themes/sunset.svg
deleted file mode 100644
index 62e620e..0000000
--- a/docs/assets/themes/sunset.svg
+++ /dev/null
@@ -1,97 +0,0 @@
-
\ No newline at end of file
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index 13879d5..0d0c037 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -1,6 +1,6 @@
---
title: Configuration
-description: The rup.config.json keys of the free edition and how flags override them.
+description: The rup.config.json keys, free and Pro, and how flags override them.
---
# Configuration
@@ -32,20 +32,28 @@ optional because the defaults below apply.
## Keys
-| Key | Default | Meaning |
-| --- | --- | --- |
-| `project` | folder name | Name used in titles |
-| `outDir` | `docs/rup` | Root of the documentation, relative to the project root |
-| `docLanguage` | `en` | Language of the documents. File names, IDs, front-matter keys and PlantUML identifiers stay in English |
-| `codeRoot` | `.` | Where the code lives; used by editions that read or generate code |
-| `paths.*` | numbered folders | Folder name of each discipline under `outDir` |
-| `useCaseDir` | `use-cases` | Subfolder that holds one folder per use case |
-| `plantuml.url` | `http://127.0.0.1:8085` | Address of the PlantUML server |
-| `plantuml.timeoutMs` | `30000` | Time allowed for one render request |
-| `diagrams.language` | `plantuml` | Diagram language. The free edition supports `plantuml` |
-| `diagrams.outputs` | `["svg"]` | Render outputs. The free edition supports `svg` |
-| `ids.*` | `RF`, `RNF`, `UC`, `RN`, `DEC`, `TC` | Prefixes of the stable identifiers |
-| `targetStack` | empty | Target stack, read by editions that generate code |
+| Key | Default | Edition | Meaning |
+| --- | --- | --- | --- |
+| `project` | folder name | Free | Name used in titles |
+| `outDir` | `docs/rup` | Free | Root of the documentation, relative to the project root |
+| `docLanguage` | `en` | Free | Language of the documents. File names, IDs, front-matter keys and PlantUML identifiers stay in English |
+| `codeRoot` | `.` | Pro | Where the code lives; read by `scan` and by code generation |
+| `paths.*` | numbered folders | Free | Folder name of each discipline under `outDir` |
+| `useCaseDir` | `use-cases` | Free | Subfolder that holds one folder per use case |
+| `plantuml.url` | `http://127.0.0.1:8085` | Free | Address of the PlantUML server |
+| `plantuml.timeoutMs` | `30000` | Free | Time allowed for one render request |
+| `diagrams.language` | `plantuml` | Free | `plantuml`. Pro: also `mermaid` |
+| `diagrams.outputs` | `["svg"]` | Free | `svg`. Pro: also `png` and `html` |
+| `ids.*` | `RF`, `RNF`, `UC`, `RN`, `DEC`, `TC` | Free | Prefixes of the stable identifiers |
+| `targetStack` | empty | Pro | Language, framework, persistence and testing of the code to generate |
+| `traceTag` | `@rup` | Pro | Doc-comment tag that links code to a model element |
+| `theme.preset` | `default` | Pro | Palette name |
+| `theme.colors.*` | none | Pro | Color overrides; `levels` takes exactly four colors |
+| `theme.font` | system font stack | Pro | Font family of the diagrams |
+| `theme.fontSize` | `14` | Pro | Font size in points |
+| `theme.roundCorner` | `6` | Pro | Corner radius of boxes |
+| `mermaid.image` | pinned image | Pro | Container image that draws Mermaid |
+| `mermaid.timeoutMs` | `180000` | Pro | Time allowed for a Mermaid batch |
## Precedence
@@ -62,8 +70,9 @@ flags > rup.config.json > defaults
Changing `paths` or `outDir` after documents exist means moving the folders and
fixing the links. Do it as one explicit step and run `check` afterwards.
-## Settings that belong to Pro
+## Pro settings in the free edition
-The free edition rejects a configuration that asks for a Mermaid diagram
-language or a non-`svg` output, and ignores nothing silently: it stops with a
-message that names Pro. Theme settings are only read by Pro.
+The free edition does not ignore a Pro setting silently. A Mermaid language or a
+non-`svg` output in the file, or any `--theme`, `--font`, `--color-*` or
+`--preview-png` flag, stops the command with a message that names Pro. `theme` and
+`mermaid` keys are only read by Pro.
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 66fe6b6..cae2dd8 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -1,39 +1,35 @@
---
title: Contributing
-description: How to improve the rup-flow documentation and the free skill.
+description: How to improve the rup-flow documentation and report problems in the skill.
---
# Contributing
## The documentation
-This site lives in [rup-flow-docs](https://github.com/hector-ae21/rup-flow-docs).
-Work on a branch, run `npm run verify` and open a pull request.
+This site lives in [rup-flow-docs](https://github.com/hector-ae21/rup-flow-docs), the only
+public repository of the project. Work on a branch, run `npm run verify` and open a pull
+request.
Rules that keep the site honest:
-- Document released behaviour of the free edition completely.
-- Describe Pro at feature level only. A reader must not be able to recreate a Pro
- capability from this site.
+- Document released behaviour. The free edition and rup-flow Pro are both documented; mark
+ every page, table row or step that belongs to Pro with `edition: pro` in the front matter
+ or the Pro tag.
+- Never document behaviour that does not exist, and never promise a roadmap item as if it
+ shipped.
- Examples contain no credentials or private data.
+- Diagrams are PlantUML sources in `docs/assets/diagrams/sources`, drawn in a light and a
+ dark look; edit the source, never the SVG.
-## The free skill
+## The skill
-The skill lives in [rup-flow](https://github.com/hector-ae21/rup-flow). Pull
-requests improve the free workflow; capabilities listed as Pro in
-`editions.json` are developed elsewhere and are not accepted there.
-
-| Check | Command |
-| --- | --- |
-| Validation and tests | `npm run check` |
-| Package the web ZIP | `node tools/package-web.mjs` |
-
-Conventional Commits, a branch per change and the `CI complete` check apply to
-both repositories. Every behaviour change needs a test and a changelog entry
-under `Unreleased`.
+The skill source is private; it is distributed as the free and Pro packages. Report a problem
+in the skill, or a client that ignores the instruction files, in the documentation
+repository's issues with the documentation template and say which edition and version
+(`RUP version`) you use.
## Reporting a problem
-Open an issue with the documentation template for this site, or a bug report in
-the skill repository. Report vulnerabilities privately as described in the
-repository security policies.
+Open an issue with the documentation template. Report vulnerabilities privately as described
+in the security policy.
diff --git a/docs/diagrams/analysis-classes.md b/docs/diagrams/analysis-classes.md
index 5ffdd80..79b0d07 100644
--- a/docs/diagrams/analysis-classes.md
+++ b/docs/diagrams/analysis-classes.md
@@ -8,9 +8,10 @@ description: The boundary, control and entity classes of the analysis discipline
The first software structure derived from the use cases: what the user touches
(boundary), what coordinates (control) and what holds information (entity).
-
+
-
+
+
@@ -54,9 +55,7 @@ OrderLine --> Product
- One control class per use case.
- Entity names are the ones in the domain model.
-
+!!! pro "In Pro"
-**Pro** adds one analysis collaboration per use case, with numbered messages,
-and the analysis card that links it to the requirements and the design.
-
-
+ Pro adds one analysis collaboration per use case, with numbered messages,
+ and the analysis card that links it to the requirements and the design.
diff --git a/docs/diagrams/domain-model-simple.md b/docs/diagrams/domain-model-simple.md
index d151e32..37c9cc0 100644
--- a/docs/diagrams/domain-model-simple.md
+++ b/docs/diagrams/domain-model-simple.md
@@ -8,9 +8,10 @@ description: The free domain diagram, how to draw it and how to read it.
The business concepts of the project and the relations between them. Attributes
and importance levels are left out; the entity dictionary carries the detail.
-
+
-
+
+
@@ -51,10 +52,8 @@ Order --> Address
`00-domain-model/README.md` holds the entity dictionary (definition, key
attributes, source) and the business rules (`RN-xxx`).
-
+!!! pro "In Pro"
-**Pro** draws the same model ranked by importance, with attributes and
-multiplicities, and adds the lifecycle of the entities whose state changes
-behaviour. See the [catalogue](index.md).
-
-
+ Pro draws the same model ranked by importance, with attributes and
+ multiplicities, and adds the lifecycle of the entities whose state changes
+ behaviour. See the [catalogue](index.md).
diff --git a/docs/diagrams/index.md b/docs/diagrams/index.md
index e4247a1..e819a68 100644
--- a/docs/diagrams/index.md
+++ b/docs/diagrams/index.md
@@ -1,108 +1,112 @@
---
title: Diagram catalogue
-description: Every diagram rup-flow draws, with the three that are free and the eleven that are part of Pro.
+description: The fourteen diagrams rup-flow draws, three free and eleven in Pro, each in a light and a dark look.
---
# Diagram catalogue
-rup-flow draws fourteen kinds of diagram. Three are free; they cover the first
-disciplines of RUP. The other eleven are part of
-[rup-flow Pro](../pro/index.md). The catalogue is the same one the CLI prints
-with `RUP editions`.
+rup-flow draws fourteen kinds of diagram from one example project, an online shop. Three are free and cover the first disciplines; the other eleven are part of rup-flow Pro. Every image follows the theme of this page. The catalogue is the one the CLI prints with `RUP editions`.
## Free
-
-
-
-
-### Simplified domain model
-
-Entities and relations, nothing else.
-
-[Read more](domain-model-simple.md)
-
-
-
-
-
-### Use-case specification
-
-The Actor/System conversation as a statechart.
-
-[Read more](specification.md)
-
-
-
-
-
-### Analysis classes
+
-Boundary, control and entity classes.
+
+{ loading=lazy }
+{ loading=lazy }
+Simplified domain modelFree
+
-[Read more](analysis-classes.md)
+
+{ loading=lazy }
+{ loading=lazy }
+Use-case specificationFree
+
-
-## Part of Pro
+## Pro Pro
-Images below are rendered by the Pro edition with the default look.
+Pro draws these from the same models and links them from the use-case cards. They are described, discipline by discipline, in [Domain model](../pro/diagrams-domain.md), [Requirements](../pro/diagrams-requirements.md) and [Analysis and design](../pro/diagrams-design.md).
-{ loading=lazy }
-Domain model ranked by importance Pro
+{ loading=lazy }
+{ loading=lazy }
+Domain model ranked by importancePro
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+Entity lifecyclesPro
-{ loading=lazy }
-Entity lifecycles Pro
+{ loading=lazy }
+{ loading=lazy }
+Use-case diagramPro
-{ loading=lazy }
-Use-case diagram, general and per actor Pro
+{ loading=lazy }
+{ loading=lazy }
+Use-case diagram per actorPro
-{ loading=lazy }
-Wireframes Pro
+{ loading=lazy }
+{ loading=lazy }
+WireframesPro
-{ loading=lazy }
-Analysis collaboration Pro
+{ loading=lazy }
+{ loading=lazy }
+Analysis collaborationPro
-{ loading=lazy }
-Design classes Pro
+{ loading=lazy }
+{ loading=lazy }
+Design classesPro
-{ loading=lazy }
-Design sequence Pro
+{ loading=lazy }
+{ loading=lazy }
+Design sequencePro
-{ loading=lazy }
-Data model Pro
+{ loading=lazy }
+{ loading=lazy }
+Data modelPro
-{ loading=lazy }
-Components Pro
+{ loading=lazy }
+{ loading=lazy }
+ComponentsPro
-{ loading=lazy }
-Deployment Pro
+{ loading=lazy }
+{ loading=lazy }
+DeploymentPro
-All fourteen can also be drawn in Mermaid, with eight palettes or your own
-colors, in Pro. See [Themes, Mermaid and the explorer](../pro/themes-and-explorer.md).
+Pro also draws every diagram in Mermaid, with eight palettes or your own colors. See [Themes](../pro/themes.md).
+
+## Conventions
+
+All diagrams follow the same [conventions](conventions.md).
diff --git a/docs/diagrams/specification.md b/docs/diagrams/specification.md
index 398eb48..f773610 100644
--- a/docs/diagrams/specification.md
+++ b/docs/diagrams/specification.md
@@ -10,9 +10,10 @@ of the conversation between the actor and the system. The card describes the
same paths in words; if they diverge, the specification wins and the card is
corrected.
-
+
-
+
+
@@ -31,10 +32,10 @@ state "createOrder" as createOrder {
state " " as Placed
[*] --> Basket
- Basket --> Checkout : Customer asks to check out
- Checkout --> Validating : Customer confirms address
- Validating --> Checkout : System reports unavailable stock or missing address
- Validating --> Placed : System creates order and reserves stock
+ Basket --> Checkout : Customer checks out
+ Checkout --> Validating : Customer confirms
+ Validating --> Checkout : System reports a problem
+ Validating --> Placed : System creates the order
Placed --> [*]
note on link
@@ -60,10 +61,8 @@ state "createOrder" as createOrder {
- Every input and every precondition has a failure path.
- The paths match the flows in the card.
-
+!!! pro "In Pro"
-**Pro** adds the wireframes of the screens of the flow, the analysis
-collaboration and the design sequence for the same use case, each linked from
-the card. See the [catalogue](index.md).
-
-
+ Pro adds the wireframes of the screens of the flow, the analysis
+ collaboration and the design sequence for the same use case, each linked from
+ the card. See the [catalogue](index.md).
diff --git a/docs/getting-started/compatible-agents.md b/docs/getting-started/compatible-agents.md
new file mode 100644
index 0000000..5d5144f
--- /dev/null
+++ b/docs/getting-started/compatible-agents.md
@@ -0,0 +1,85 @@
+---
+title: Compatible agents
+description: How rup-flow reaches Claude, Codex, Gemini, Cursor, Copilot, Windsurf, Cline and any other coding agent.
+---
+
+# Compatible agents
+
+rup-flow does not depend on one agent. It reaches them in three ways.
+
+
+
+
+
+
+
+
+## 1. The agent reads Agent Skills
+
+The skill follows the open [Agent Skills](https://agentskills.io/specification)
+format. A client that reads it loads `SKILL.md` and the references on demand. Put
+the folder where the client looks for skills ([installation](installation.md)).
+
+## 2. The agent reads an instruction file
+
+Tools that read a rules file get a small block that points them at the skill. The
+`instructions` command writes it, replaces it between its markers when you run it
+again and never touches the rest of the file:
+
+```console
+node scripts/rup.mjs instructions --target cursor,windsurf --root .
+```
+
+| Target | File it writes | Agents and editors |
+| --- | --- | --- |
+| `agents` | `AGENTS.md` | Codex, Cursor, Copilot agent, Gemini CLI, opencode, Zed, Jules and others |
+| `claude` | `CLAUDE.md` | Claude Code |
+| `gemini` | `GEMINI.md` | Gemini CLI |
+| `copilot` | `.github/copilot-instructions.md` | GitHub Copilot |
+| `cursor` | `.cursor/rules/rup-flow.mdc` | Cursor |
+| `windsurf` | `.windsurf/rules/rup-flow.md` | Windsurf |
+| `cline` | `.clinerules/rup-flow.md` | Cline |
+| `roo` | `.roo/rules/rup-flow.md` | Roo Code |
+| `kilo` | `.kilocode/rules/rup-flow.md` | Kilo Code |
+| `continue` | `.continue/rules/rup-flow.md` | Continue |
+| `junie` | `.junie/guidelines.md` | JetBrains Junie |
+| `amazonq` | `.amazonq/rules/rup-flow.md` | Amazon Q Developer |
+| `zed` | `.rules` | Zed |
+| `aider` | `CONVENTIONS.md` | Aider, loaded with `--read CONVENTIONS.md` |
+| `portable` | `RUP-FLOW.md` | Any other agent |
+
+The locations follow each tool's documented convention at the time of writing. If a
+tool changed its folder, write the `portable` file and point the tool at it, or use
+`--skill-path` to say where the skill lives.
+
+## 3. Any other agent with a shell
+
+An agent that can read a file and run a command can use rup-flow. Write the
+portable file, tell the agent to read it, and it follows the same rules and runs the
+same CLI:
+
+```console
+node scripts/rup.mjs instructions --target portable --root .
+```
+
+```text title="Prompt"
+Read RUP-FLOW.md and use rup-flow to document this system in docs/rup.
+```
+
+## What every agent must be able to do
+
+| Capability | Why |
+| --- | --- |
+| Read files and the skill folder | The rules and references are plain Markdown |
+| Run `node` | The CLI is a Node.js program |
+| Write files | The documents are Markdown and PlantUML |
+
+An agent that cannot run commands can still write the documents by following the
+references, but it cannot render or check them; it must say so.
+
+## What is tested
+
+The automated tests check that every target writes its file, keeps the rest of an
+existing file, does not duplicate its block, and that the skill installs into both
+skill folders. What an agent does with the files is up to the agent; report a client
+that ignores them.
diff --git a/docs/getting-started/first-documentation.md b/docs/getting-started/first-documentation.md
index caf09f1..38282a9 100644
--- a/docs/getting-started/first-documentation.md
+++ b/docs/getting-started/first-documentation.md
@@ -40,8 +40,7 @@ docs/rup/
└── 05-quality/ open-questions.md
```
-Open `docs/rup/README.md` and follow the links. A complete rendered example is
-in the repository: [examples/shop](https://github.com/hector-ae21/rup-flow/tree/main/examples/shop).
+Open `docs/rup/README.md` and follow the links.
## Check it yourself
diff --git a/docs/getting-started/how-it-works.md b/docs/getting-started/how-it-works.md
index fbbb217..8f9ef50 100644
--- a/docs/getting-started/how-it-works.md
+++ b/docs/getting-started/how-it-works.md
@@ -5,11 +5,12 @@ description: The parts of rup-flow and what each one is responsible for.
# How rup-flow works
-```text
-you ──► agent ──► SKILL.md + references ──► documents (Markdown)
- │
- └──► CLI (rup.mjs) ──► PlantUML server ──► SVG diagrams
-```
+
+
+
+
+
+
## The skill
@@ -19,8 +20,9 @@ for each request. The references (`methodology`, `domain-model`, `use-cases`,
attention on your project, not on boilerplate.
The skill is written once in the open
-[Agent Skills](https://agentskills.io/specification) format and adapted per
-client by small adapters (plugin manifest, installer, instruction files).
+[Agent Skills](https://agentskills.io/specification) format. Agents that do not read
+that format read a small instruction file instead; see
+[Compatible agents](compatible-agents.md).
## The CLI
@@ -33,6 +35,7 @@ A dependency-free Node.js program does the mechanical work:
| Draws `.puml` sources into `.svg` | `render` |
| Verifies structure, links and diagrams | `check` |
| Writes the block that agents without skills read | `instructions` |
+| Tells what is installed | `version`, `editions` |
## The operating rules
@@ -49,6 +52,6 @@ See [Provenance marks](../reference/provenance.md) and the
## Editions
-The same CLI runs both editions. rup-flow Pro adds an extension that the CLI
-loads when it is present; without it, the CLI is the free edition. Read
-[Editions and the extension point](../architecture/editions.md).
+The same CLI runs both editions. rup-flow Pro adds an extension that the CLI loads
+when it is present; without it, the CLI is the free edition and says so when you ask
+for something outside it. Read [Editions and the extension point](../architecture/editions.md).
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
index 36d0dc7..0f4bc1a 100644
--- a/docs/getting-started/index.md
+++ b/docs/getting-started/index.md
@@ -11,8 +11,8 @@ skill and runs the CLI.
-**What you need:** Node.js 18 or newer and an agent that reads the Agent Skills
-format. Docker is optional and only draws the diagrams.
+**What you need:** Node.js 18 or newer, a shell and an AI coding agent. Docker is
+optional and only draws the diagrams.
@@ -24,11 +24,11 @@ format. Docker is optional and only draws the diagrams.
01 · Install
-### Install rup-flow
+## Install rup-flow
-Claude Code, Claude on the web, or any client that reads `.agents/skills`.
+Unzip the skill into the skills folder of your agent, or let the installer do it.
-[Choose your client](installation.md)
+[Choose your agent](installation.md)
@@ -36,7 +36,7 @@ Claude Code, Claude on the web, or any client that reads `.agents/skills`.
02 · Document
-### Document your first system
+## Document your first system
One prompt, a folder of documents and diagrams, and a check.
@@ -48,7 +48,7 @@ One prompt, a folder of documents and diagrams, and a check.
03 · Understand
-### See how it works
+## See how it works
The skill, the CLI, the PlantUML server and what each one is responsible for.
@@ -56,6 +56,18 @@ The skill, the CLI, the PlantUML server and what each one is responsible for.
+
+
+04 · Fit
+
+## Check your agent
+
+Which agents read the skill directly and which read an instruction file.
+
+[See compatible agents](compatible-agents.md)
+
+
+
## What the free edition produces
@@ -67,5 +79,7 @@ The skill, the CLI, the PlantUML server and what each one is responsible for.
| Analysis | `02-analysis` | Analysis classes (boundary, control, entity) |
| Quality | `05-quality` | Open questions |
-Design, implementation, traceability, audits and code are part of
-[rup-flow Pro](../pro/index.md).
+!!! pro "In Pro"
+
+ Design, implementation, traceability, audits and code in both directions
+ complete the other folders. See [the complete documentation set](../pro/documentation-set.md).
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 90b57d7..e871c18 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -1,11 +1,13 @@
---
title: Install rup-flow
-description: Install the free rup-flow skill in Claude Code, Claude on the web, or any agent that reads Agent Skills.
+description: Install the rup-flow skill, free or Pro, for Claude, Codex, Gemini and any other agent.
---
# Install rup-flow
-Pick the client you use. All of them install the same skill.
+Both editions are one folder, `rup-flow` (free) or `rup-flow-pro` (Pro), that you
+place where your agent looks for skills. They are the same skill: install one of
+them in a given place, not both.
## Check the runtime
@@ -13,55 +15,85 @@ Pick the client you use. All of them install the same skill.
node --version
```
-The skill needs Node.js 18 or newer. Docker is only needed to draw diagrams
-(see [Render and check diagrams](../guides/render-and-check.md)).
+The skill needs Node.js 18 or newer. Docker is only needed to draw diagrams (see
+[Render and check diagrams](../guides/render-and-check.md)).
-## Choose your client
+## Get the package
-=== "Claude Code"
+| Edition | File | Where it comes from |
+| --- | --- | --- |
+| Free | `rup-flow-free-.zip` | The marketplace listing of rup-flow (free) |
+| Pro | `rup-flow-pro-.zip` | The marketplace listing of rup-flow Pro, see [Get Pro](../pro/get-pro.md) |
+
+The version is part of the file name. After installing, `rup.mjs version` prints
+it.
+
+## Put it where your agent looks
- Add the marketplace and install the plugin:
+Unzip so that the folder lands inside the skills folder of your agent.
+
+=== "Claude Code"
```console
- claude plugin marketplace add hector-ae21/rup-flow
- claude plugin install rup-flow@rup-flow
+ unzip rup-flow-free-1.0.0.zip -d ~/.claude/skills
```
- Then say "Use rup-flow to ..." or run `/rup-flow:rup-flow`.
+ Use `.claude/skills` inside a project to install it for that project only. Then
+ say "Use rup-flow to ..." or run `/rup-flow`.
=== "Claude on the web"
- 1. Download `rup-flow-skill.zip` from the
- [latest release](https://github.com/hector-ae21/rup-flow/releases/latest).
- 2. In **Customize → Skills**, upload the ZIP.
-
- The web sandbox cannot reach a PlantUML server on your machine, so diagrams
- stay as `.puml` sources there; render them locally later.
+ In **Customize → Skills**, upload the ZIP. The web sandbox cannot reach a
+ PlantUML server on your machine, so diagrams stay as `.puml` sources there;
+ render them locally later.
=== "Codex, Gemini CLI and others"
```console
- git clone https://github.com/hector-ae21/rup-flow
- cd rup-flow
- node install.mjs --target agents
+ unzip rup-flow-free-1.0.0.zip -d ~/.agents/skills
```
- The skill lands in `.agents/skills/rup-flow` under your home folder. Use
- `--project ` to install it for one project only.
+ Clients that read `.agents/skills` pick it up. Say "Use rup-flow to ...".
-## Verify the installation
+=== "Any other folder"
+
+ Every client lists its own skills folder in its documentation. Unzip there:
+
+ ```console
+ unzip rup-flow-free-1.0.0.zip -d
+ ```
-Ask the agent to run the CLI, or run it yourself from the skill folder:
+On Windows, use the file manager or `Expand-Archive`:
+
+```console
+Expand-Archive rup-flow-free-1.0.0.zip -DestinationPath $HOME\.claude\skills
+```
+
+## Agents that read an instruction file
+
+Cursor, GitHub Copilot, Windsurf, Cline and many others do not load skills; they
+read an instruction file. After unzipping the skill somewhere in the project, write
+the file the agent reads:
+
+```console
+node .agents/skills/rup-flow/scripts/rup.mjs instructions --target cursor
+```
+
+See [Compatible agents](compatible-agents.md) for every target.
+
+## Verify the installation
```console
-node scripts/rup.mjs editions
+node /rup-flow/scripts/rup.mjs version
+node /rup-flow/scripts/rup.mjs editions
```
-The first line says `this installation: free`. The list below it shows what
-the free edition includes and what is part of Pro.
+`version` prints `rup-flow free 1.0.0` or `rup-flow Pro 1.0.0 (built on rup-flow
+free 1.0.0)`. `editions` lists what the installation includes; the first line says
+`free` or `Pro`.
-## Other agents
+## Update
-Cursor and GitHub Copilot read instruction files instead of skills. The
-`instructions` command writes the block they need; see
-[Use another agent](../guides/other-agents.md).
+Unzip the new package over the old folder, or replace the folder. Your
+documentation and `rup.config.json` live in your project and are not touched. See
+[Update rup-flow](../releases/updating.md).
diff --git a/docs/guides/index.md b/docs/guides/index.md
index cfee946..7791bd7 100644
--- a/docs/guides/index.md
+++ b/docs/guides/index.md
@@ -41,9 +41,9 @@ Start the PlantUML server, render, and read the `check` output.
## Use another agent
-Codex, Gemini CLI, Cursor and GitHub Copilot.
+Codex, Gemini, Cursor, Copilot, Windsurf, Cline and more.
-[Read the guide](other-agents.md)
+[See compatible agents](../getting-started/compatible-agents.md)
diff --git a/docs/guides/other-agents.md b/docs/guides/other-agents.md
deleted file mode 100644
index 0cc93f6..0000000
--- a/docs/guides/other-agents.md
+++ /dev/null
@@ -1,46 +0,0 @@
----
-title: Use another agent
-description: Use rup-flow with Codex, Gemini CLI, Cursor, GitHub Copilot and other clients.
----
-
-# Use another agent
-
-## Clients that read Agent Skills
-
-Codex, Gemini CLI and other clients that read `.agents/skills` use the skill as
-it is:
-
-```console
-git clone https://github.com/hector-ae21/rup-flow
-cd rup-flow
-node install.mjs --target agents
-```
-
-Use `--project ` to install into one project, `--force` to replace an
-existing install (a backup is kept) and `--list` to see the targets.
-
-## Clients that read instruction files
-
-Cursor and GitHub Copilot read instruction files. The `instructions` command
-adds or refreshes a delimited block in the file each client loads, without
-touching the rest of it:
-
-```console
-node scripts/rup.mjs instructions --target agents,claude,gemini,copilot,cursor --root .
-```
-
-| Target | File |
-| --- | --- |
-| `agents` | `AGENTS.md` (Codex, Cursor, Copilot agent, Gemini CLI, Zed, Jules and others) |
-| `claude` | `CLAUDE.md` |
-| `gemini` | `GEMINI.md` |
-| `copilot` | `.github/copilot-instructions.md` |
-| `cursor` | `.cursor/rules/rup-flow.mdc` |
-
-Running it again replaces the block between its markers and never duplicates it.
-Use `--skill-path ` when the skill is installed somewhere else.
-
-## Tested clients
-
-Claude Code, Claude on the web, Codex and Gemini CLI are tested. Cursor and
-Copilot are supported through instruction files.
diff --git a/docs/index.md b/docs/index.md
index 33edd92..c98ce24 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,5 +1,5 @@
---
-title: RUP documentation and code, from your AI coding agent
+title: RUP documentation and code, from any AI coding agent
description: Turn requirements into RUP documentation with your AI coding agent. The free edition covers the basics; rup-flow Pro covers the whole workflow, in both directions.
hide:
- toc
@@ -9,14 +9,15 @@ hide:
-
RUP documentation skill · rup-flow 0.4
+
RUP documentation skill · rup-flow 1.0
# Document your system and build it from the same models
rup-flow teaches your AI coding agent to turn requirements
into RUP models and diagrams. The free edition covers the first disciplines.
rup-flow Pro covers the whole workflow, from requirements to code and from
-legacy code back to models, with evidence for every claim.
+legacy code back to models, with evidence for every claim. It works with
+Claude, Codex, Gemini, Cursor, Copilot and any agent with a shell.
@@ -26,7 +27,7 @@ legacy code back to models, with evidence for every claim.
- Works with the agent you use
+ Any coding agentNever invents requirementsNode.js only
@@ -43,14 +44,15 @@ legacy code back to models, with evidence for every claim.
## One workflow, two editions
-
The free edition is a complete, working sample. It
-stops where the project gets serious, and tells you so instead of improvising.
+
Every page of this site says which edition it
+describes. Pages and rows marked Pro belong to
+rup-flow Pro; everything else is in the free edition.
-### Free
+## Free Free
The simplified domain model, actors, requirements, use cases with their
specification statechart, analysis classes and open questions, drawn with
@@ -62,9 +64,9 @@ PlantUML. MIT licensed.
-### Pro
+## Pro Pro
-The ranked domain model, every diagram type, design, implementation and
+The ranked domain model, fourteen diagram types, design, implementation and
traceability, code in both directions, themes, Mermaid, the interactive
explorer, stack packs, domain libraries and subagents.
@@ -74,10 +76,10 @@ explorer, stack packs, domain libraries and subagents.
-### Compared
+## Compared
-Every diagram, document, workflow and tool, marked free or Pro, generated from
-the same catalogue the CLI prints.
+Every diagram, document, workflow and tool, marked free or Pro, from the same
+catalogue the CLI prints.
[Compare the editions](pro/compare.md)
@@ -91,16 +93,16 @@ the same catalogue the CLI prints.
-### Every statement has a provenance
+## Every statement has a provenance
-*Confirmed* by you, *assumed* by the agent, or *open* as a question. An
-assumption is never written as a fact.
+*Confirmed* by you, *observed* in code, *assumed* by the agent or *open* as a
+question. An assumption is never written as a fact.
-### Unknown rules become questions
+## Unknown rules become questions
Missing business rules go to `open-questions.md` instead of being invented to
make a document look complete.
@@ -109,7 +111,7 @@ make a document look complete.
-### The agent says what it did not do
+## The agent says what it did not do
Diagrams are not called rendered or checked unless the render ran and the result
was looked at. Anything outside your edition is named, not improvised.
@@ -144,8 +146,9 @@ diagrams and checks the result. Open `docs/rup/README.md` and follow the links.
-**Current documentation:** this site describes rup-flow `0.4`. Use the version
-selector when you operate another release line so commands and configuration
-match the skill you installed.
+**Current documentation:** this site describes rup-flow `1.0` (free) and rup-flow
+Pro `1.0`. Use the version selector when you operate another release line so
+commands and configuration match the skill you installed.
+[How versions map](releases/versioning.md)
diff --git a/docs/pro/code-to-rup.md b/docs/pro/code-to-rup.md
new file mode 100644
index 0000000..aae29c5
--- /dev/null
+++ b/docs/pro/code-to-rup.md
@@ -0,0 +1,63 @@
+---
+title: Code to RUP
+description: How rup-flow Pro documents an existing code base, with every claim backed by a location in the code.
+edition: pro
+since: "1.0"
+---
+
+# Code to RUP
+
+Point the agent at a code base and ask for its documentation. Pro writes the same
+documentation set as for a new system, but every statement describes what the code
+**does**, marked *observed* and cited as `path:line`. The artifacts carry
+`origin: code` and `sourceOfTruth: code`.
+
+```text title="Prompt"
+Use rup-flow-pro to reverse engineer src/ into docs/rup, in English.
+```
+
+## The procedure
+
+1. **Inventory.** `RUP scan --code-root --write` lists the manifests, entry points,
+ entities, services, persistence, contracts and tests, so the agent starts from facts.
+2. **Stack and architecture.** Identified from manifests and folder layout and recorded in
+ the project configuration document.
+3. **Domain model.** Persistence first (schema, migrations, ORM models), then entity
+ classes. One entity per business concept, not per table: join and technical tables are
+ support entities or omitted with a note.
+4. **Levels.** The agent asks for the project objective, or infers it from the README and
+ the entry points and marks it *assumed*, then assigns the levels.
+5. **Use cases.** Derived from the entry points: each route, command handler, job, message
+ consumer or CLI command that achieves a user goal. Technical endpoints that serve one
+ goal become one use case.
+6. **Specification.** The agent follows the code path of each use case: validation,
+ branching, errors, side effects. The statechart shows only behaviour found in code. A
+ branch that cannot be understood is an open question, not a guess.
+7. **Analysis and design.** Classes, sequences, data model and deployment are drawn from
+ the real call graph, the configuration and the deployment files (Dockerfile, compose,
+ CI, infrastructure as code).
+8. **Code map and traceability.** Every model element gets its location; the `code`
+ column of the traceability table is filled.
+9. **Tests.** Existing tests fill the `test` column; use cases without tests are gaps.
+10. **Render, check, review.**
+
+## Rules the agent follows
+
+- It writes behaviour, not intent. Intent that the code does not reveal, such as why a
+ rule exists, is a question.
+- Dead code, TODOs and inconsistent behaviour are findings in the audit, not silent fixes
+ in the model.
+- It cites `path:line` instead of pasting code.
+- It reads files fully before describing them; it never describes from names alone.
+- On large code bases it works module by module and keeps a coverage list of what was and
+ was not read.
+
+## What you get at the end
+
+The files created, the entities and use cases found, the parts not covered and the open
+questions. Statements it could not support are never presented as facts.
+
+## Related
+
+[Sync and audit](sync-and-audit.md) · [RUP to code](rup-to-code.md) ·
+[Provenance marks](../reference/provenance.md)
diff --git a/docs/pro/code.md b/docs/pro/code.md
deleted file mode 100644
index afcfd52..0000000
--- a/docs/pro/code.md
+++ /dev/null
@@ -1,47 +0,0 @@
----
-title: Code in both directions
-description: What rup-flow Pro does with code - reverse engineering, generation, drift detection and audits.
----
-
-# Code in both directions
-
-## Code to RUP
-
-Point the agent at a code base and ask for its documentation. Pro inventories the
-code, reads the parts that matter and writes the same documentation set, with each
-claim marked *observed* and cited as `path:line`. Business rules it cannot read in
-the code become questions, not invented requirements.
-
-## RUP to code
-
-From reviewed models, Pro generates code and tests that follow the conventions of
-your code base, with a trace link from each class or handler to the requirement
-and use case it implements. Open questions that affect a use case stop its
-generation, and nothing outside the requested use cases is written.
-
-The agent runs the build, the tests and the linters of your project and reports
-the result as it is. Whatever it could not run is reported as unverified.
-
-## Drift detection
-
-When code and documentation both exist and may disagree, Pro produces a table of
-differences:
-
-| Kind | Meaning |
-| --- | --- |
-| Model ahead | The documentation describes something the code does not do yet |
-| Code ahead | The code does something the documentation does not mention |
-| Conflict | Both exist and disagree |
-| Dead | An element that nothing refers to |
-
-## Audit
-
-A read-only review of the documentation and its alignment with the code, with
-findings that carry evidence, severity, impact and a proposed fix. The review
-states which checks it could not execute.
-
-## Honest limits
-
-Generated code is only as good as the reviewed models and your tests. The audit
-validates structure, links and traceability gaps; it does not prove that UML is
-semantically correct.
diff --git a/docs/pro/compare.md b/docs/pro/compare.md
index 965ead8..1f57eb7 100644
--- a/docs/pro/compare.md
+++ b/docs/pro/compare.md
@@ -1,75 +1,77 @@
---
title: Free and Pro compared
-description: Every diagram, document, workflow and tool of rup-flow, marked free or Pro.
+description: Every diagram, document, workflow and tool of rup-flow, marked free or Pro, with a link to where it is documented.
+edition: pro
+since: "1.0"
---
# Free and Pro compared
-The free edition is a sample of the full workflow: it shows how rup-flow works and gives you the first disciplines. [rup-flow Pro](index.md) is the complete workflow. This table is the catalogue the CLI prints with `RUP editions`.
+The free edition is a working sample of the workflow: it gives you the first disciplines. [rup-flow Pro](index.md) is the complete workflow. This is the catalogue the CLI prints with `RUP editions`; the last column says where each item is documented.
## Diagrams
-| | Free | Pro |
-| --- | :---: | :---: |
-| Simplified domain model | Included | Included |
-| Use-case specification (Actor/System statechart) | Included | Included |
-| Analysis classes (boundary, control, entity) | Included | Included |
-| Domain model ranked by importance, with attributes and multiplicities | — | Included |
-| Entity lifecycle (state diagram) | — | Included |
-| Use-case diagram with packages, include and extend | — | Included |
-| One use-case diagram per actor | — | Included |
-| Wireframes for every screen of a use case | — | Included |
-| Analysis collaboration per use case | — | Included |
-| Design classes | — | Included |
-| Design sequence per use case | — | Included |
-| Data model | — | Included |
-| Components and interfaces | — | Included |
-| Deployment | — | Included |
+| | Free | Pro | Documented in |
+| --- | :---: | :---: | --- |
+| Simplified domain model | Included | Included | [Read](../diagrams/domain-model-simple.md) |
+| Use-case specification (Actor/System statechart) | Included | Included | [Read](../diagrams/specification.md) |
+| Analysis classes (boundary, control, entity) | Included | Included | [Read](../diagrams/analysis-classes.md) |
+| Domain model ranked by importance, with attributes and multiplicities | — | Included | [Read](diagrams-domain.md) |
+| Entity lifecycle (state diagram) | — | Included | [Read](diagrams-domain.md) |
+| Use-case diagram with packages, include and extend | — | Included | [Read](diagrams-requirements.md) |
+| One use-case diagram per actor | — | Included | [Read](diagrams-requirements.md) |
+| Wireframes for every screen of a use case | — | Included | [Read](diagrams-requirements.md) |
+| Analysis collaboration per use case | — | Included | [Read](diagrams-design.md) |
+| Design classes | — | Included | [Read](diagrams-design.md) |
+| Design sequence per use case | — | Included | [Read](diagrams-design.md) |
+| Data model | — | Included | [Read](diagrams-design.md) |
+| Components and interfaces | — | Included | [Read](diagrams-design.md) |
+| Deployment | — | Included | [Read](diagrams-design.md) |
## RUP documentation
-| | Free | Pro |
-| --- | :---: | :---: |
-| Domain README: entity dictionary and business rules | Included | Included |
-| Actors | Included | Included |
-| Requirements catalogue (functional and non-functional) | Included | Included |
-| Use-case requirements card | Included | Included |
-| Analysis README | Included | Included |
-| Open questions | Included | Included |
-| Domain hierarchy of levels | — | Included |
-| Use-case analysis card | — | Included |
-| Use-case design card | — | Included |
-| Use-case implementation and tests card | — | Included |
-| Design README and project configuration | — | Included |
-| Code map | — | Included |
-| Project profile | — | Included |
-| Traceability table | — | Included |
-| Audit report and decision records | — | Included |
+| | Free | Pro | Documented in |
+| --- | :---: | :---: | --- |
+| Domain README: entity dictionary and business rules | Included | Included | [Read](../reference/folder-structure.md) |
+| Actors | Included | Included | [Read](../reference/folder-structure.md) |
+| Requirements catalogue (functional and non-functional) | Included | Included | [Read](../reference/folder-structure.md) |
+| Use-case requirements card | Included | Included | [Read](../guides/use-cases.md) |
+| Analysis README | Included | Included | [Read](../reference/folder-structure.md) |
+| Open questions | Included | Included | [Read](../reference/provenance.md) |
+| Domain hierarchy of levels | — | Included | [Read](documentation-set.md) |
+| Use-case analysis card | — | Included | [Read](use-case-cards.md) |
+| Use-case design card | — | Included | [Read](use-case-cards.md) |
+| Use-case implementation and tests card | — | Included | [Read](use-case-cards.md) |
+| Design README and project configuration | — | Included | [Read](documentation-set.md) |
+| Code map | — | Included | [Read](documentation-set.md) |
+| Project profile | — | Included | [Read](documentation-set.md) |
+| Traceability table | — | Included | [Read](documentation-set.md) |
+| Audit report and decision records | — | Included | [Read](sync-and-audit.md) |
## Workflows
-| | Free | Pro |
-| --- | :---: | :---: |
-| Requirements to domain, requirements and analysis documents | Included | Included |
-| Provenance marks: confirmed, observed, assumed, open | Included | Included |
-| Code to RUP (reverse engineering with evidence) | — | Included |
-| RUP to code with trace links | — | Included |
-| Drift detection between documentation and code | — | Included |
-| Audit and review of the documentation | — | Included |
-| Architect and reviewer subagents | — | Included |
+| | Free | Pro | Documented in |
+| --- | :---: | :---: | --- |
+| Requirements to domain, requirements and analysis documents | Included | Included | [Read](../guides/document-a-system.md) |
+| Provenance marks: confirmed, observed, assumed, open | Included | Included | [Read](../reference/provenance.md) |
+| Code to RUP (reverse engineering with evidence) | — | Included | [Read](code-to-rup.md) |
+| RUP to code with trace links | — | Included | [Read](rup-to-code.md) |
+| Drift detection between documentation and code | — | Included | [Read](sync-and-audit.md) |
+| Audit and review of the documentation | — | Included | [Read](sync-and-audit.md) |
+| Architect and reviewer subagents | — | Included | [Read](subagents.md) |
## Tooling
-| | Free | Pro |
-| --- | :---: | :---: |
-| CLI: init, new use-case, index, render, check, instructions | Included | Included |
-| PlantUML rendering through a local Docker server | Included | Included |
-| Eight palettes, custom colors and fonts | — | Included |
-| Mermaid as a second diagram language | — | Included |
-| PNG previews | — | Included |
-| Interactive explorer (search, relations, PNG and SVG export) | — | Included |
-| Stack packs for code generation | — | Included |
-| Ready-made domain libraries | — | Included |
+| | Free | Pro | Documented in |
+| --- | :---: | :---: | --- |
+| CLI: init, new use-case, index, render, check, instructions | Included | Included | [Read](../reference/cli.md) |
+| PlantUML rendering through a local Docker server | Included | Included | [Read](../guides/render-and-check.md) |
+| Eight palettes, custom colors and fonts | — | Included | [Read](themes.md) |
+| Mermaid as a second diagram language | — | Included | [Read](mermaid.md) |
+| PNG previews | — | Included | [Read](mermaid.md) |
+| Interactive explorer (search, relations, PNG and SVG export) | — | Included | [Read](explorer.md) |
+| Stack packs for code generation | — | Included | [Read](packs.md) |
+| Ready-made domain libraries | — | Included | [Read](domain-libraries.md) |
## Keep going
@@ -77,7 +79,7 @@ The free edition is a sample of the full workflow: it shows how rup-flow works a
-### See what Pro adds
+## See what Pro adds
The areas Pro covers and why they matter.
@@ -87,7 +89,7 @@ The areas Pro covers and why they matter.
-### Get Pro
+## Get Pro
Where to get it and what you receive.
diff --git a/docs/pro/diagrams-design.md b/docs/pro/diagrams-design.md
new file mode 100644
index 0000000..7622647
--- /dev/null
+++ b/docs/pro/diagrams-design.md
@@ -0,0 +1,78 @@
+---
+title: Analysis and design diagrams
+description: The collaboration, design classes, sequence, data model, components and deployment diagrams of rup-flow Pro.
+edition: pro
+since: "1.0"
+---
+
+# Analysis and design diagrams
+
+## Analysis collaboration
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+One per use case: the actor, the boundary used, the control that coordinates and the entities touched, with numbered messages. Boundaries talk only to controls; entities never call upward.
+
+## Design classes
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+Packages by layer or feature, as recorded in a decision, with the operations each class exposes. Interfaces appear where a dependency must be inverted.
+
+## Design sequence
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+Messages between concrete design elements, including the failure path as an alt block and the transaction boundary as a note. It must follow the same paths as the specification.
+
+## Data model
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+Tables or collections with keys, relations and constraints, mapped from the entities and listed with that mapping. Lines are drawn for foreign keys only.
+
+## Components
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+Components grouped by layer, the interfaces they provide and require, and which component implements each interface. Dependencies point at interfaces, not at implementations.
+
+## Deployment
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+Nodes, containers, external systems and the protocols on the links.
+
+## Related
+
+[The complete documentation set](documentation-set.md) · [RUP to code](rup-to-code.md)
diff --git a/docs/pro/diagrams-domain.md b/docs/pro/diagrams-domain.md
new file mode 100644
index 0000000..a02fab0
--- /dev/null
+++ b/docs/pro/diagrams-domain.md
@@ -0,0 +1,40 @@
+---
+title: Domain model diagrams
+description: The ranked domain model and the entity lifecycles of rup-flow Pro.
+edition: pro
+since: "1.0"
+---
+
+# Domain model diagrams
+
+The free edition draws entities and relations. Pro draws the same model **ranked by importance**, with the attributes that matter and the multiplicity of every relation, and adds the lifecycle of the entities whose state changes behaviour.
+
+## Ranked domain model
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+- One package per level, level 1 on top, tagged so the palette colors the bands.
+- Relations point downwards where the meaning allows; a relation that points upwards is legitimate but is a signal to re-check the levels.
+- Multiplicities on every relation, and composition only when the part cannot live without the whole.
+- Attributes that carry business meaning or that a use case needs. Trivial ones are omitted and the README says so in an "omitted attributes and why" column.
+- Hidden links hold the order of the bands and of the entities inside one band, so the diagram reads the same after every change.
+
+## Entity lifecycles
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+Only entities whose state changes behaviour get one. Each transition names the use case that causes it, so the lifecycle and the use cases cannot drift apart.
+
+## Related
+
+[The complete documentation set](documentation-set.md) · [Themes](themes.md) · [Diagram conventions](../diagrams/conventions.md)
diff --git a/docs/pro/diagrams-requirements.md b/docs/pro/diagrams-requirements.md
new file mode 100644
index 0000000..a3d01e7
--- /dev/null
+++ b/docs/pro/diagrams-requirements.md
@@ -0,0 +1,50 @@
+---
+title: Requirements diagrams
+description: The use-case diagrams and the wireframes of rup-flow Pro.
+edition: pro
+since: "1.0"
+---
+
+# Requirements diagrams
+
+## Use-case diagram
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+- Actors stay outside the system boundary; packages group related use cases inside it.
+- `include` and `extend` relations come from the front matter of the cards.
+- An actor is linked only to the use cases that no other use case of that actor includes.
+- It is regenerated by `RUP index` from the cards: never edit it by hand.
+
+## One diagram per actor
+
+When there are several actors, Pro also draws a diagram per actor with only the use cases that actor triggers, plus the ones they include or extend.
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+## Wireframes
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+- One sketch per screen of the flow, drawn as a PlantUML salt layout so it stays text.
+- Every field shown maps to a domain attribute or a parameter of the use case; every attribute the use case needs appears in some screen.
+- Wireframes are PlantUML also when the project uses Mermaid, because Mermaid has no wireframe diagram.
+
+## Related
+
+[Use-case cards](use-case-cards.md) · [Use-case specification](../diagrams/specification.md)
diff --git a/docs/pro/documentation-set.md b/docs/pro/documentation-set.md
index a2e3d8a..cb849bc 100644
--- a/docs/pro/documentation-set.md
+++ b/docs/pro/documentation-set.md
@@ -1,40 +1,101 @@
---
title: The complete documentation set
-description: The artifacts rup-flow Pro adds to the free edition, discipline by discipline.
+description: Every artifact rup-flow Pro writes, discipline by discipline, and the rules that keep them consistent.
+edition: pro
+since: "1.0"
---
# The complete documentation set
-Pro writes all six disciplines into the same numbered folders the free edition
-uses, so a project moves to Pro without renaming anything.
+Pro writes all six disciplines into the same numbered folders the free edition uses,
+so a project moves to Pro without renaming anything. Each artifact has a front matter
+that records its identifier, status, origin and source of truth; see
+[Front matter and identifiers](../reference/front-matter.md).
| Discipline | Free | Pro adds |
| --- | --- | --- |
-| `00-domain-model` | Simplified model, dictionary, rules | The model ranked by importance with attributes and multiplicities, and the lifecycle of entities whose state changes behaviour |
-| `01-requirements` | Actors, requirements, use-case card, specification | Use-case diagrams, general and per actor, with packages, include and extend; wireframes for every screen |
-| `02-analysis` | Analysis classes | One collaboration per use case and its analysis card |
-| `03-design` | — | Design classes, sequence per use case, data model, components, deployment, project configuration |
-| `04-implementation` | — | Code map and one implementation and tests card per use case |
-| `05-quality` | Open questions | Project profile, traceability table, audit report and decision records |
+| `00-domain-model` | Simplified model, dictionary, rules | Ranked model, levels, attributes, multiplicities, entity lifecycles |
+| `01-requirements` | Actors, requirements, use-case card, specification | Use-case diagrams, wireframes, navigation between cards |
+| `02-analysis` | Analysis classes | Collaboration per use case, analysis card |
+| `03-design` | none | Design classes, sequence per use case, data model, components, deployment, project configuration |
+| `04-implementation` | none | Code map, implementation and tests card per use case |
+| `05-quality` | Open questions | Project profile, traceability, audit, decision records |
-## One card per discipline
+## 00 Domain model
-Every use case has a card in requirements, analysis, design and implementation.
-All four start with the same navigation table, so you move between disciplines
-without hunting for files.
+The model is organised in four horizontal bands. The higher the band, the more
+central the entity is to the project objective written in the project profile.
-## Traceability
+| Level | Meaning | Test |
+| --- | --- | --- |
+| 1 Core | The reason the project exists | Without it the objective is not met |
+| 2 Structural | Depend directly on level 1 and give it shape | Cannot exist or make sense without a level-1 entity |
+| 3 Detail | Qualify, specialise or break down level 2 | Removing it loses precision, not purpose |
+| 4 Support | Catalogues, audit, configuration | Replaceable without changing the business meaning |
+
+- The README justifies the levels for the project. The same concept can be level 1 in
+ one project and level 4 in another.
+- Position is a reading aid: it never implies inheritance or composition.
+- At most three to five entities per level; a band that grows is split into a
+ sub-model with the simple model kept as the map.
+- Only entities whose state changes behaviour get a lifecycle diagram, and each
+ transition names the use case that causes it.
+
+See [Domain model diagrams](diagrams-domain.md).
+
+## 01 Requirements
+
+- The use-case diagram groups use cases in packages inside the system boundary, with
+ actors outside it; `include` and `extend` come from the cards' front matter. A
+ separate diagram is drawn per actor when there are several.
+- Every use case has a wireframe for each screen of its flow. Every field shown maps to
+ a domain attribute or a parameter of the use case.
+
+See [Requirements diagrams](diagrams-requirements.md) and [Use-case cards](use-case-cards.md).
+
+## 02 Analysis
+
+One collaboration per use case: the actor, the boundary it uses, the control that
+coordinates and the entities touched, with numbered messages. Boundaries talk only to
+controls, controls talk to entities and other controls, entities never call upward.
+
+## 03 Design
+
+Design classes and their operations, a sequence per use case with its failure path and
+transaction boundary, the data model with its mapping from entities, the components with
+the interfaces they provide and require, the deployment, and the project configuration
+(stack, build, run, environment variables). Each non-obvious choice becomes a decision
+record. The use-case design card lists the design elements that realize it, which is
+what [RUP to code](rup-to-code.md) reads.
+
+See [Analysis and design diagrams](diagrams-design.md).
+
+## 04 Implementation
+
+The code map lists every model element and its location. Each use case has a card with
+the code and the tests that implement it.
+
+## 05 Quality
-Each requirement, use case, analysis, design, code location and test sits in one
-table. Empty cells are gaps that `check` reports.
+| Artifact | Holds |
+| --- | --- |
+| Project profile | Objective, scope, constraints, stack, who confirms what |
+| Traceability | Requirement, use case, analysis, design, code and test, one row per use case |
+| Open questions | Every unknown, who asked, what it blocks |
+| Audit | Findings with evidence, severity, impact and fix, and the checks not executed |
+| Decision records | One `DEC-xxx` per decision and its reasons |
-## Consistency
+## Consistency rules
-Pro treats the models as the single source of truth for what they describe. A
-change in one artifact is propagated to the dependent ones, and the table is
-updated in the same change.
+- The models are the single source of truth for what they describe, unless an artifact
+ says `sourceOfTruth: code`.
+- A change in one artifact is propagated to the dependent ones, and the traceability
+ table is updated in the same change.
+- Every requirement has at least one use case; every use case has at least one
+ requirement.
+- `check` reports gaps: a use case without realization, an empty code or test cell,
+ a row missing from the traceability table.
## Example
-The repository ships a complete example project, an online shop, with every
-artifact above. See [Free and Pro compared](compare.md) for the full catalogue.
+The Pro package ships a complete example, an online shop, with every artifact above.
diff --git a/docs/pro/domain-libraries.md b/docs/pro/domain-libraries.md
new file mode 100644
index 0000000..1c8f649
--- /dev/null
+++ b/docs/pro/domain-libraries.md
@@ -0,0 +1,78 @@
+---
+title: Domain libraries
+description: Ready starting points for common domains in rup-flow Pro, and the lms library in detail.
+edition: pro
+since: "1.0"
+---
+
+# Domain libraries
+
+A domain library is a starting point for a project whose objective matches a known
+domain: a ranked domain model, actors, a list of use cases, the entity lifecycles and
+the questions to ask before using it. Libraries live in the `domains` folder of the Pro
+skill.
+
+Everything in a library is marked *assumed*. The agent adapts it to your objective,
+asks you to confirm each rule and moves what is not confirmed to the open questions. It
+never presents a library as your requirements.
+
+## Included
+
+| Library | Domain |
+| --- | --- |
+| `lms` | Learning platforms: courses, enrolment, activities, grading, completion |
+
+More libraries are announced in the [Pro changelog](versions.md).
+
+## `lms`
+
+The agent offers it when the objective mentions courses, enrolment, learners and
+teachers, activities, grading or completion.
+
+### Entities
+
+| Entity | Level | Definition |
+| --- | --- | --- |
+| Enrolment | 1 | A learner's participation in a course |
+| Course | 1 | A taught unit with sections and activities |
+| Learner | 2 | Person who takes courses |
+| Teacher | 2 | Person who runs a course and grades |
+| Section | 2 | Ordered block of a course |
+| Activity | 3 | Something the learner does |
+| Submission | 3 | A learner's attempt at an activity |
+| Grade | 3 | Mark given to a submission |
+| Category | 4 | Catalogue classification of courses |
+
+### Rules to confirm
+
+- A learner has at most one active enrolment per course.
+- A learner can submit only to a course in which the enrolment is active.
+- A grade is between zero and the activity's maximum grade.
+- A course is completed for a learner when all required activities have an accepted
+ grade.
+- Only a teacher of the course can grade its submissions.
+- A cancelled enrolment keeps its submissions and grades.
+
+### Actors and use cases
+
+Learner, Teacher, Manager and a notification system. The starting use cases are
+`enrolInCourse`, `cancelEnrolment`, `submitActivity`, `gradeSubmission`,
+`completeCourse`, `publishCourse` and `reviewProgress`, each with its package and the
+rules it touches.
+
+### Lifecycle
+
+The enrolment moves from active to cancelled or completed; whether a learner can
+re-enrol is a question the library asks.
+
+### Questions it asks before use
+
+1. Can a learner re-enrol after cancelling, or after failing?
+2. Is there a pass mark, and is it per activity or per course?
+3. Does grading allow several graders or a re-grade, and are previous grades kept?
+4. Is enrolment self-service, approved by a teacher or assigned by a manager?
+5. Is completion calculated or declared by a teacher?
+
+## Related
+
+[Stack packs](packs.md) · [The complete documentation set](documentation-set.md)
diff --git a/docs/pro/explorer.md b/docs/pro/explorer.md
new file mode 100644
index 0000000..222a714
--- /dev/null
+++ b/docs/pro/explorer.md
@@ -0,0 +1,78 @@
+---
+title: The interactive explorer
+description: One self-contained page to browse, search and trace every diagram of a project, with an overview, relation tracing and exports.
+edition: pro
+since: "1.0"
+---
+
+# The interactive explorer
+
+`RUP explore`, or `RUP render --outputs svg,html`, writes `explorer.html` in the
+documentation directory: one file with every rendered diagram of the project and the
+documents next to them. It needs no server and loads nothing from the network, so it
+opens from the file system and can be attached to an email or a ticket.
+
+## Overview
+
+It opens on an overview: a thumbnail of every diagram, grouped by discipline or by use
+case. Search narrows the grid; a click opens the diagram.
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+## Trace relations
+
+Click an element to highlight what it is connected to and dim the rest. Choose how far
+to go, direct relations or everything reachable, in the panel, which also lists the
+related elements and jumps to each one.
+
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
+
+## What else it does
+
+| Feature | Detail |
+| --- | --- |
+| Fit to window | Every diagram opens fitted and centered; `f` fits, `w` fits the width, `0` is actual size |
+| Pan and zoom | Drag to pan, wheel to zoom, with the zoom level on screen |
+| Global search | Searches the text of every diagram; results are counted per diagram |
+| Find in diagram | Highlights matches and dims the rest |
+| Grouping | By discipline or by use case |
+| Siblings | Chips jump between the diagrams of the same use case or section |
+| Source | The PlantUML or Mermaid source of the diagram, with a copy button |
+| Document | The Markdown card that sits next to the diagram, with links that open other documents and diagrams inside the explorer |
+| Export | The current diagram as SVG or as a 2x PNG |
+| Deep links | Copy a link to the exact view: diagram, tab, selected element, search and mode |
+| Light and dark | Follows the system mode and remembers your choice; diagrams stay on a white sheet in both |
+| Full screen and print | Full screen button; printing hides the chrome |
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| `/` | Search all diagrams |
+| `h` | Overview |
+| `j` `→` / `k` `←` | Next and previous diagram |
+| `f` `w` `0` | Fit, fit width, actual size |
+| `+` `-` | Zoom |
+| `1` `2` `3` | Diagram, source, document |
+| `d` | Dark page |
+| `Esc` | Clear the selection, the search and the help |
+| `?` | Show the shortcuts |
+
+## Safety
+
+The page has a content security policy that blocks every external load. Diagrams and
+documents are inserted as nodes, never as raw HTML, so a document cannot run script.
+
+## Related
+
+[Themes](themes.md) · [Mermaid and PNG previews](mermaid.md)
diff --git a/docs/pro/get-pro.md b/docs/pro/get-pro.md
index af98d48..b912622 100644
--- a/docs/pro/get-pro.md
+++ b/docs/pro/get-pro.md
@@ -1,53 +1,72 @@
---
title: Get Pro
-description: Where to get rup-flow Pro and what you receive.
+description: Where to get rup-flow Pro, what you receive and how to install and update it.
+edition: pro
+since: "1.0"
---
# Get Pro
## What you receive
-- The `rup-flow-pro` skill, as a ZIP and ready for the clients that read Agent
- Skills.
+- The `rup-flow-pro-.zip` package: the Pro skill, ready for the agents that read
+ Agent Skills and for the ones that read an instruction file.
- Every update published while your license is active.
-- The stack packs, domain libraries and subagents of the release.
+- The stack packs, domain libraries and subagent definitions of the release.
+- The complete example project.
## Where
-rup-flow Pro is listed on [Agensi](https://www.agensi.io), the marketplace for
-agent skills. Search for `rup-flow-pro` and follow the listing, which shows the
-current price and the latest version.
+rup-flow Pro is listed on [Agensi](https://www.agensi.io), the marketplace for agent
+skills. Search for `rup-flow` and open the Pro listing, which shows the current price and
+the latest version.
## Install it
-The package installs like any skill:
+Unzip so that the `rup-flow-pro` folder lands in the skills folder of your agent, the same
+way as the free edition ([installation](../getting-started/installation.md)):
=== "Claude Code"
- Unzip `rup-flow-pro` into `~/.claude/skills/` (or `.claude/skills/` in a
- project) and copy the files in its `agents/` folder to `~/.claude/agents/`.
- Then say "Use rup-flow-pro to ...".
+ ```console
+ unzip rup-flow-pro-1.0.0.zip -d ~/.claude/skills
+ ```
+
+ Copy the files of `rup-flow-pro/agents` to `~/.claude/agents` to enable the
+ [subagents](subagents.md). Then say "Use rup-flow-pro to ...".
=== "Claude on the web"
- Upload `rup-flow-pro-skill.zip` in **Customize → Skills**.
+ Upload the ZIP in **Customize → Skills**.
=== "Codex, Gemini CLI and others"
- Unzip `rup-flow-pro` into `~/.agents/skills/`.
+ ```console
+ unzip rup-flow-pro-1.0.0.zip -d ~/.agents/skills
+ ```
+
+=== "Instruction-file agents"
+
+ Unzip the skill into the project, then write the file your agent reads:
+
+ ```console
+ node .agents/skills/rup-flow-pro/scripts/rup.mjs instructions --target cursor
+ ```
-Install either the free skill or Pro in a given place, not both: they are the
-same skill and the Pro one replaces the free one.
+Install the free skill or Pro in a given place, not both: Pro replaces the free skill,
+and contains it.
## Verify
```console
-node scripts/rup.mjs editions
+node /rup-flow-pro/scripts/rup.mjs version
+node /rup-flow-pro/scripts/rup.mjs editions
```
-The first line says `this installation: Pro`, and no item is marked as missing.
+`version` prints the Pro version and the free version it contains. `editions` says
+`this installation: Pro` and marks nothing as missing.
-## Updating
+## Update
-Install the new package over the old one. Your documentation and your
-configuration are not touched. Read the changelog first.
+Unzip the new package over the old folder. Your documentation and configuration are not
+touched. Read the [Pro changelog](versions.md) first.
diff --git a/docs/pro/index.md b/docs/pro/index.md
index bc3ad8c..fe3aa53 100644
--- a/docs/pro/index.md
+++ b/docs/pro/index.md
@@ -1,22 +1,22 @@
---
title: rup-flow Pro
description: The complete rup-flow workflow, from requirements to code and from code back to models, with every diagram, themes and the interactive explorer.
+edition: pro
+since: "1.0"
---
# rup-flow Pro
-The free edition gets you through requirements. Pro takes the same project the
-rest of the way: models you can trust, code that traces back to them, and
-documentation that stays honest as the code changes.
+The free edition gets you through requirements. Pro takes the same project the rest
+of the way: models you can trust, code that traces back to them, and documentation
+that stays honest as the code changes.
-
+!!! info "One skill, two editions"
-**Pro is a separate product.** It is not a fork: it is the free skill with an
-extension laid over it, so everything you learned in the free edition applies.
-It is described here at feature level; the free documentation covers the shared
-parts completely.
-
-
+ Pro is not a fork. It is the free skill with an extension laid over it, so
+ everything you learned in the free edition applies, and every free page of this
+ site still describes how Pro behaves. This section documents what Pro adds, in
+ detail.
## What Pro adds
@@ -24,11 +24,10 @@ parts completely.
-### The complete documentation set
+## The complete documentation set
-The ranked domain model, entity lifecycles, use-case diagrams, wireframes,
-analysis, design, implementation and quality artifacts, linked by one
-navigation table per use case.
+The ranked domain model, entity lifecycles, use-case diagrams, wireframes, analysis,
+design, implementation and quality artifacts.
[See the set](documentation-set.md)
@@ -36,34 +35,34 @@ navigation table per use case.
-### Code in both directions
+## Code in both directions
-Reverse engineering with evidence, code generation with trace links, drift
-detection and audits.
+Reverse engineering with evidence, code generation with trace links, drift detection
+and audits.
-[See the workflows](code.md)
+[Code to RUP](code-to-rup.md) · [RUP to code](rup-to-code.md) · [Sync and audit](sync-and-audit.md)
-### Themes, Mermaid and the explorer
+## Themes, Mermaid and the explorer
-Eight palettes or your own colors, Mermaid as a second language, PNG previews
-and an interactive explorer.
+Eight palettes or your own colors, Mermaid as a second language, PNG previews and an
+interactive explorer.
-[See the look](themes-and-explorer.md)
+[Themes](themes.md) · [Mermaid](mermaid.md) · [Explorer](explorer.md)
-### Packs, libraries and subagents
+## Packs, libraries and subagents
Stack packs, ready domain libraries and two subagents that generate and review
independently.
-[See the extras](packs-and-agents.md)
+[Stack packs](packs.md) · [Domain libraries](domain-libraries.md) · [Subagents](subagents.md)
@@ -71,7 +70,12 @@ independently.
## See it
-{ loading=lazy }
+
+
+{ loading=lazy }
+{ loading=lazy }
+
+
## Is Pro for you?
@@ -81,7 +85,14 @@ independently.
| Inherit code nobody documented | Documentation derived from the code, each claim cited with its location |
| Have docs and code that drift apart | A table of differences: model ahead, code ahead, conflict, dead |
| Need a deliverable for a course, a client or an audit | A complete, traceable, consistently styled set |
-| Want the agent to build from reviewed models | Code, tests and `@rup` trace links generated from them |
+| Want the agent to build from reviewed models | Code, tests and trace links generated from them |
+
+## How Pro is versioned
+
+Pro has its own version, `1.0.0` today, and always states the free version it
+contains: `rup.mjs version` prints `rup-flow Pro 1.0.0 (built on rup-flow free 1.0.0)`.
+Pages and rows of this site marked Pro say since
+which Pro version they apply. See [Pro versions and compatibility](versions.md).
## Next
diff --git a/docs/pro/license-and-support.md b/docs/pro/license-and-support.md
index 33fcc40..42aa76e 100644
--- a/docs/pro/license-and-support.md
+++ b/docs/pro/license-and-support.md
@@ -1,6 +1,8 @@
---
title: License and support
description: The terms of rup-flow Pro and how to get help.
+edition: pro
+since: "1.0"
---
# License and support
@@ -16,14 +18,13 @@ The free rup-flow skill is MIT licensed. rup-flow Pro is proprietary.
| Receive the updates published while your license is active | Give your copy or your access to people without a license |
A team needs one license per person. The license ends if you breach it; what you
-already generated stays yours. The full text ships inside the package as
-`LICENSE.md`.
+already generated stays yours. The full text ships inside the package as `LICENSE.md`.
## Support
- Questions and defects in the documentation:
[open an issue](https://github.com/hector-ae21/rup-flow-docs/issues).
-- Defects in the free edition: [rup-flow issues](https://github.com/hector-ae21/rup-flow/issues).
+- Defects in the skill, free or Pro: the same issue tracker, saying which edition and version (`RUP version`) you use.
- Support is best effort and runs through those channels.
Do not paste Pro package content into public issues.
diff --git a/docs/pro/mermaid.md b/docs/pro/mermaid.md
new file mode 100644
index 0000000..3239bb5
--- /dev/null
+++ b/docs/pro/mermaid.md
@@ -0,0 +1,70 @@
+---
+title: Mermaid and PNG previews
+description: Draw every rup-flow Pro diagram in Mermaid instead of PlantUML, and add PNG previews.
+edition: pro
+since: "1.0"
+---
+
+# Mermaid and PNG previews
+
+## Mermaid
+
+Choose Mermaid instead of PlantUML as the diagram language of a project. The documents,
+the structure and the palettes are the same; only the language of the sources changes
+(`.mmd` instead of `.puml`).
+
+```console
+RUP init --diagram-language mermaid --theme ocean
+```
+
+Or in the configuration:
+
+```json
+{ "diagrams": { "language": "mermaid" } }
+```
+
+### Equivalents
+
+| Artifact | Mermaid type | Notes |
+| --- | --- | --- |
+| Domain model, analysis classes, design classes | `classDiagram` with `direction TB` | Levels through `:::level1` to `:::level4` |
+| Entity lifecycle, specification | `stateDiagram-v2` | The composite state carries the use-case name; notes narrate Actor and System |
+| Collaboration | `flowchart TB` | Numbered edge labels |
+| Sequence | `sequenceDiagram` | `alt` and `else` for failure paths |
+| Data model | `erDiagram` | |
+| Deployment | `flowchart TB` with `subgraph` | |
+| Use-case diagram | `flowchart LR` | Mermaid has no use-case diagram, so it is drawn as a flowchart with the same grouping |
+
+Labels with parentheses, colons or line breaks are quoted.
+
+### Rendering
+
+- Mermaid is drawn by the mermaid-cli container, pulled the first time you use it (about
+ 1 GB). Docker must be running.
+- Wireframes stay PlantUML salt layouts, so `server up` is still needed in a Mermaid
+ project.
+- `render` handles `.puml` and `.mmd` together; do not mix languages for one diagram.
+
+## PNG previews
+
+A raster preview next to each PlantUML diagram, for tools that cannot show SVG:
+
+```console
+RUP render --preview-png
+```
+
+Each `name.svg` gets a `name.preview.png`. Previews are PlantUML only.
+
+## Outputs
+
+`diagrams.outputs` or `--outputs` accepts any of:
+
+| Output | Produces |
+| --- | --- |
+| `svg` | The image that Markdown embeds |
+| `png` | `.preview.png` next to each PlantUML diagram |
+| `html` | The [interactive explorer](explorer.md) |
+
+## Related
+
+[Themes](themes.md) · [Command line](../reference/cli.md)
diff --git a/docs/pro/packs-and-agents.md b/docs/pro/packs-and-agents.md
deleted file mode 100644
index ed7e1b6..0000000
--- a/docs/pro/packs-and-agents.md
+++ /dev/null
@@ -1,42 +0,0 @@
----
-title: Packs, libraries and subagents
-description: Stack packs, domain libraries and the architect and reviewer subagents included in rup-flow Pro.
----
-
-# Packs, libraries and subagents
-
-## Stack packs
-
-A stack pack fixes how reviewed models become code for one stack: folder layout,
-naming, error handling, persistence mapping and test patterns. The agent reads
-the pack that matches your configuration before generating code, and it takes
-precedence over the generic mapping.
-
-| Pack | Stack |
-| --- | --- |
-| `nestjs-prisma` | TypeScript, NestJS, Prisma and Jest |
-
-More packs follow in later releases; they are listed in the changelog.
-
-## Domain libraries
-
-A domain library is a starting point: a ranked domain model, actors, a list of
-use cases, entity lifecycles and the questions to ask before using it. Everything
-in a library is marked *assumed*; the agent adapts it to your objective and never
-presents it as your requirements.
-
-| Library | Domain |
-| --- | --- |
-| `lms` | Learning platforms: courses, enrolment, activities, grading, completion |
-
-## Subagents
-
-For clients that support subagents (Claude Code does), Pro includes two:
-
-| Subagent | Does |
-| --- | --- |
-| `rup-architect` | Generates and updates the models and generates code from reviewed models |
-| `rup-reviewer` | Read-only auditor of the documentation and its alignment with the code |
-
-They run independently, so the review is not written by the one who wrote the
-documents. Without subagents, the review runs as a separate pass.
diff --git a/docs/pro/packs.md b/docs/pro/packs.md
new file mode 100644
index 0000000..846797b
--- /dev/null
+++ b/docs/pro/packs.md
@@ -0,0 +1,79 @@
+---
+title: Stack packs
+description: What a stack pack is, how the agent uses it and what the nestjs-prisma pack covers in rup-flow Pro.
+edition: pro
+since: "1.0"
+---
+
+# Stack packs
+
+A stack pack fixes how reviewed models become code for one stack: the folder layout,
+the naming, the error handling, the persistence mapping and the test patterns. The
+agent reads the pack that matches `targetStack` before it plans code, and the pack takes
+precedence over the generic mapping of [RUP to code](rup-to-code.md).
+
+Packs live in the `packs` folder of the Pro skill: a `PACK.md` and, where useful,
+fill-in skeletons.
+
+## Included
+
+| Pack | Stack |
+| --- | --- |
+| `nestjs-prisma` | TypeScript, NestJS, Prisma on PostgreSQL and Jest |
+
+More packs are announced in the [Pro changelog](versions.md).
+
+## `nestjs-prisma`
+
+### Architecture
+
+- Organised by **feature package**, one per concept of the domain model, with concrete
+ classes. No layers of ports and abstract factories that the models do not ask for.
+- One class per file, the file named after the class; one reason to change per class.
+- A use case is one service; a controller only translates HTTP into a service call.
+- Dependencies are injected collaborators such as the Prisma service and the config
+ service, never singletons.
+- Business rules live in entity methods or in the use-case service, never in the
+ controller.
+
+### What it generates per feature
+
+| File | Comes from |
+| --- | --- |
+| Module and controller | The boundary classes of the analysis |
+| Request and response objects | The wireframe fields and the use-case card, validated with decorators |
+| One service per use case | The design sequence, step by step |
+| Mapper | Only where the response differs from the entity |
+| Unit test | One test per flow and per rule |
+
+### From the data model to Prisma
+
+| Model | Prisma |
+| --- | --- |
+| Entity | A `model` mapped to the table name of the data model |
+| Primary key | A UUID unless the data model fixes another type |
+| Relation with multiplicity | Relation fields on both sides, foreign key on the many side, cascade when the part cannot outlive the whole |
+| Unique rule | `@unique` or `@@unique` |
+| Entity lifecycle | An `enum`, with transitions guarded in the service |
+| Timestamps | Created and updated columns |
+
+One migration per feature; an applied migration is never edited.
+
+### Services, errors and tests
+
+- A service validates the request, loads what the sequence loads in its order, applies
+ the rules, throws a typed exception per failure path, persists inside one transaction
+ when the sequence marks a boundary and returns the response.
+- Exceptions are mapped to HTTP in one filter.
+- Unit tests mock the persistence service; one test per main flow, alternative flow and
+ rule, named with the identifier. End-to-end tests send one request per main flow.
+- Trace links are TSDoc tags (`@rup UC-001 RF-001`); no narrative comments elsewhere.
+
+### Before it reports done
+
+It validates the Prisma schema, type-checks, runs the linter and the tests, and reports
+each result as it is. Anything it did not run is reported as unverified.
+
+## Related
+
+[Domain libraries](domain-libraries.md) · [RUP to code](rup-to-code.md)
diff --git a/docs/pro/rup-to-code.md b/docs/pro/rup-to-code.md
new file mode 100644
index 0000000..771b09a
--- /dev/null
+++ b/docs/pro/rup-to-code.md
@@ -0,0 +1,81 @@
+---
+title: RUP to code
+description: How rup-flow Pro generates code and tests from reviewed models, with trace links to the requirements.
+edition: pro
+since: "1.0"
+---
+
+# RUP to code
+
+From reviewed models, Pro generates code and tests that follow the conventions of your
+code base, with a link from each class or handler to the requirement and use case it
+implements.
+
+```text title="Prompt"
+Use rup-flow-pro to implement UC-001 from the design.
+```
+
+## Preconditions
+
+- The use cases to implement are at least `reviewed`. Drafts are listed and the agent
+ asks before generating from them.
+- `targetStack` is set in the configuration. If it is empty the agent asks for the
+ language, framework, persistence and testing, and saves the answers.
+- The output goes to `codeRoot` unless you pass another path; nothing is written outside
+ the project.
+- Blocking items in the open questions that affect a use case stop the generation of that
+ use case.
+
+## How a model becomes code
+
+| Model element | Code element |
+| --- | --- |
+| Domain entity or design class | Type or class with the same name; attributes from the dictionary |
+| Relation with multiplicity | Typed reference or collection; foreign key in persistence |
+| Business rule `RN-xxx` | Validation or domain method, with one test per rule |
+| Use case `UC-xxx` | One application service or handler named after the use case |
+| `<>` | Controller, route or screen |
+| `<>` and sequence | Application service orchestrating the steps in the sequence order |
+| Repository interface | Interface in the domain or application, implementation in persistence |
+| Data model table | Migration plus mapping |
+| Specification states | Branches and error results of the handler |
+| Wireframe fields | Request and response contract and form fields |
+| Deployment | Dockerfile, compose or manifests |
+
+A [stack pack](packs.md) that matches your configuration refines this mapping for that
+stack.
+
+## The run
+
+1. The agent lists the files it will create or change per use case and shows the plan
+ before writing when there are more than about five files.
+2. It creates the types and the persistence from the design data model.
+3. It implements each use case following its sequence step by step, including the
+ failure paths of the specification.
+4. It generates tests: one per main flow, per alternative flow and per business rule.
+ Test names cite the flow or rule identifier.
+5. It adds the trace link in the doc comment of each class or handler:
+
+ ```text
+ /** Creates an order. @rup UC-001 RF-001 */
+ ```
+
+ The tag is `traceTag` in the configuration, `@rup` by default.
+6. It runs the build, the tests and the linters of your project and reports the results
+ as they are.
+7. It updates the code map and the `code` and `test` columns of the traceability table.
+ An artifact that was deliberately changed in code is set to `sourceOfTruth: code`, or
+ the model is fixed; they are never left divergent.
+
+## Rules the agent follows
+
+- The conventions already present in the code base win over generic ones.
+- A decision the model does not contain stops the generation: the agent records a
+ question and proposes options.
+- Nothing is generated beyond the requested use cases.
+- Code that could not be built or tested in the environment is reported as unverified.
+
+## Related
+
+[Code to RUP](code-to-rup.md) · [Sync and audit](sync-and-audit.md) ·
+[Subagents](subagents.md)
diff --git a/docs/pro/subagents.md b/docs/pro/subagents.md
new file mode 100644
index 0000000..f29d578
--- /dev/null
+++ b/docs/pro/subagents.md
@@ -0,0 +1,48 @@
+---
+title: Subagents
+description: The rup-architect and rup-reviewer subagents of rup-flow Pro, and what to do in agents that have no subagents.
+edition: pro
+since: "1.0"
+---
+
+# Subagents
+
+For clients that support subagents, Pro includes two definitions in the `agents` folder
+of the skill. They split the work so that the review is not written by the one who wrote
+the documents.
+
+| Subagent | Does | Tools |
+| --- | --- | --- |
+| `rup-architect` | Generates and updates the models, in any direction, and generates code from reviewed models | Read, write, edit, search and shell |
+| `rup-reviewer` | Read-only audit of the documentation and its alignment with the code | Read and search only |
+
+## `rup-architect`
+
+It loads the Pro skill, reads the configuration, follows the workflow that matches the
+request (requirements to RUP, code to RUP, RUP to code or sync), marks every statement
+as confirmed, observed, assumed or open, writes only inside the documentation folder and
+the code folder, renders and checks before finishing, and ends with the files changed,
+the open questions, the checks it did not execute and the next step.
+
+## `rup-reviewer`
+
+It applies the audit and sync guides. It cannot write files or run commands, so it states
+which checks it could not execute. It returns a table of findings with identifier,
+severity, evidence, impact and fix, and separates format defects, consistency defects,
+missing information, drift with the code and unexecuted checks. It does not rewrite
+artifacts.
+
+## Installing them
+
+Copy the files of the skill's `agents` folder to the agents folder of your client, for
+Claude Code `~/.claude/agents` or `.claude/agents` in a project. The definitions use the
+common frontmatter of name, description and tools.
+
+## Without subagents
+
+An agent that has no subagents does the review as a separate pass after generating, following the audit guide, and
+keeps that pass read-only. Nothing else changes.
+
+## Related
+
+[Sync and audit](sync-and-audit.md) · [RUP to code](rup-to-code.md)
diff --git a/docs/pro/sync-and-audit.md b/docs/pro/sync-and-audit.md
new file mode 100644
index 0000000..7edc51e
--- /dev/null
+++ b/docs/pro/sync-and-audit.md
@@ -0,0 +1,74 @@
+---
+title: Sync and audit
+description: Drift detection between documentation and code, and the read-only audit of the documentation in rup-flow Pro.
+edition: pro
+since: "1.0"
+---
+
+# Sync and audit
+
+## Drift detection
+
+Use it when documentation and code both exist and either may have moved. For every row
+of the traceability table and the code map, the agent checks:
+
+1. The cited code location exists.
+2. The entity attributes, relations and constraints in code match the dictionary and the
+ data model.
+3. The handler of the use case follows the branches of the specification and the order of
+ the sequence.
+4. The business rules are present, and tested.
+5. There is no code behaviour (endpoints, jobs, events) without a use case.
+
+Each difference is classified:
+
+| Kind | Meaning | Default resolution |
+| --- | --- | --- |
+| Model ahead | The model says something the code lacks | Implement it, when the model is the source of truth |
+| Code ahead | The code does something the model lacks | Document it, when the code is the source of truth, otherwise ask |
+| Conflict | Both exist and disagree | Ask which is right and record a decision |
+| Dead | Code or a model element nobody uses | Report it; nothing is deleted without approval |
+
+`sourceOfTruth` decides the default direction and a conflict is never resolved silently.
+After resolving, both sides and the traceability row change in the same change, and each
+resolved conflict becomes a decision record. The output of a run is a table of
+differences with evidence and then the chosen action, never a rewrite of everything.
+
+## Audit
+
+A review of the documentation and its alignment with the code. It is read-only unless you
+ask for fixes.
+
+| Dimension | Looks for |
+| --- | --- |
+| Completeness | Requirements without a use case, use cases without a requirement, realization, wireframes or specification |
+| Consistency | Names, attributes and rules that differ between domain, use cases, analysis, design and data model |
+| Domain hierarchy | Levels without justification, everything at level 1, relations that contradict the levels |
+| Behaviour | Flows without failure paths, preconditions not checked, unreachable states |
+| Traceability | Empty cells, reused identifiers, code-map locations that do not exist |
+| Non-functional | Requirements without a measure, missing security or permission rules |
+| Diagrams | Missing SVG, syntax errors, crossing lines, unreadable labels, too many elements |
+| Provenance | Assumptions written as facts, rules without a source |
+| Drift | Differences with the code |
+
+### Findings
+
+```text
+| ID | Severity | Finding | Evidence | Impact | Fix | Status |
+```
+
+Severity is **blocker** (the artifact cannot be trusted or built), **major** (wrong or
+missing content) or **minor** (style, clarity). Evidence is a file path and the quoted
+element; there is no finding without evidence.
+
+### What the audit never claims
+
+It never states that the project is "complete RUP", that the UML is semantically
+correct or that a diagram is clean unless it was inspected. It states what was checked
+and how, and lists the checks that were not executed, for example the visual inspection
+of the rendered images.
+
+## Related
+
+[Subagents](subagents.md) · [Code to RUP](code-to-rup.md) ·
+[Decision records](documentation-set.md)
diff --git a/docs/pro/themes-and-explorer.md b/docs/pro/themes-and-explorer.md
deleted file mode 100644
index 5106d67..0000000
--- a/docs/pro/themes-and-explorer.md
+++ /dev/null
@@ -1,58 +0,0 @@
----
-title: Themes, Mermaid and the explorer
-description: The look and the navigation of rup-flow Pro diagrams - palettes, custom colors, Mermaid, PNG previews and the interactive explorer.
----
-
-# Themes, Mermaid and the explorer
-
-## Palettes and colors
-
-Diagram sources never carry colors. Pro applies the look when it draws, so the
-sources stay clean and one change restyles everything. You choose from eight
-palettes, override single colors with your own, and set the font.
-
-
-
-
-{ loading=lazy }
-Default
-
-
-
-{ loading=lazy }
-Ocean
-
-
-
-{ loading=lazy }
-Forest
-
-
-
-{ loading=lazy }
-Dark
-
-
-
-
-## Mermaid
-
-Choose Mermaid instead of PlantUML as the diagram language of a project. The
-same documents, the same structure and the same palettes apply.
-
-{ loading=lazy }
-
-## PNG previews
-
-A raster preview next to each diagram, for tools that cannot show SVG.
-
-## The interactive explorer
-
-One self-contained page with every diagram of the project. Search the text of
-all diagrams, select an element to highlight its relations, read the use-case
-cards beside the diagrams and export what you see as PNG or SVG.
-
-{ loading=lazy }
-
-The explorer needs no server: it opens from the file system and loads nothing
-from the network.
diff --git a/docs/pro/themes.md b/docs/pro/themes.md
new file mode 100644
index 0000000..9361a5e
--- /dev/null
+++ b/docs/pro/themes.md
@@ -0,0 +1,132 @@
+---
+title: Themes
+description: The eight palettes of rup-flow Pro, how to override colors and fonts, and why diagram sources never carry colors.
+edition: pro
+since: "1.0"
+---
+
+# Themes
+
+Diagram sources never carry colors. Pro applies the look when it draws, so the sources
+stay clean and one change restyles everything. Changing the palette redraws every
+diagram on the next `render`.
+
+## The palettes
+
+| Preset | Character |
+| --- | --- |
+| `default` | Neutral blue-gray on white; safe for any document |
+| `ocean` | Blues and teals |
+| `forest` | Greens, calm and low contrast |
+| `sunset` | Warm oranges and reds |
+| `grape` | Purples |
+| `mono` | Grayscale; prints well in black and white |
+| `dark` | Dark background, light lines |
+| `high-contrast` | Black on white and yellow, for accessibility |
+
+
+
+
+{ loading=lazy }
+default
+
+
+
+{ loading=lazy }
+ocean
+
+
+
+{ loading=lazy }
+forest
+
+
+
+{ loading=lazy }
+sunset
+
+
+
+{ loading=lazy }
+grape
+
+
+
+{ loading=lazy }
+mono
+
+
+
+{ loading=lazy }
+dark
+
+
+
+{ loading=lazy }
+high-contrast
+
+
+
+
+## Choosing
+
+```console
+RUP themes
+RUP render --theme ocean
+```
+
+Or in `rup.config.json`:
+
+```json
+{ "theme": { "preset": "ocean" } }
+```
+
+## Your own colors
+
+Override single colors on top of a preset, in the configuration or with a flag:
+
+| Color | What it paints |
+| --- | --- |
+| `background` | Page of the diagram |
+| `text` | Text |
+| `line` | Lines and arrows |
+| `border` | Borders of boxes |
+| `primary` | Boxes |
+| `secondary` | Groups and packages |
+| `accent` | Highlights |
+| `note` | Notes |
+| `levels` | Exactly four colors, one per domain-model level |
+
+```json
+{ "theme": { "preset": "ocean", "colors": { "accent": "#0A7A5A" } } }
+```
+
+```console
+RUP render --theme ocean --color-accent "#0A7A5A"
+```
+
+Colors must be `#RRGGBB`; a wrong value or a wrong number of `levels` stops the render
+with a message.
+
+## Fonts and shape
+
+| Setting | Flag | Default |
+| --- | --- | --- |
+| `theme.font` | `--font` | A sans-serif stack |
+| `theme.fontSize` | `--font-size` | `14` |
+| `theme.roundCorner` | none | `6` |
+
+## Rules for sources
+
+- Never write colors, `skinparam` color lines, init blocks or `classDef` colors into a
+ diagram to style it: that overrides the palette.
+- In the domain model, each level package is tagged `<>` to `<>` in
+ PlantUML (`:::level1` in Mermaid) and the renderer colors it from `levels`.
+- Stereotypes such as `<>`, `<>` and `<>` are content and
+ stay.
+- Wireframes are PlantUML salt layouts and are not themed.
+
+## Related
+
+[Mermaid and PNG previews](mermaid.md) · [The interactive explorer](explorer.md) ·
+[Configuration](../configuration/index.md)
diff --git a/docs/pro/use-case-cards.md b/docs/pro/use-case-cards.md
new file mode 100644
index 0000000..7962f2c
--- /dev/null
+++ b/docs/pro/use-case-cards.md
@@ -0,0 +1,62 @@
+---
+title: Use-case cards
+description: The four cards of a use case in rup-flow Pro and how they link to each other.
+edition: pro
+since: "1.0"
+---
+
+# Use-case cards
+
+In the free edition a use case has one card, the requirements card. In Pro it has one
+card per discipline, so the story of a use case can be followed from the requirement to
+the test.
+
+| Card | Folder | Holds |
+| --- | --- | --- |
+| Requirements | `01-requirements/use-cases/` | Actor, goal, flows, rules, specification, wireframes |
+| Analysis | `02-analysis/use-cases/` | Participating classes with one responsibility each, collaboration |
+| Design | `03-design/use-cases/` | The elements that realize it, sequence, failure path |
+| Implementation | `04-implementation/use-cases/` | Code locations, tests table |
+
+`RUP new use-case ` creates all four, assigns the next identifier, adds the row to
+the traceability table and refreshes the index.
+
+## One navigation table
+
+Every card of a use case starts with the same table, so you move between disciplines
+without hunting for files:
+
+```text
+| Overview | Requirements | Analysis | Design | Implementation | Tests |
+```
+
+The current discipline is bold, the others are links, Overview opens the general
+use-case diagram and Tests opens the tests table of the implementation card. The table
+is generated; do not retype it.
+
+## The index
+
+The requirements README holds, between `rup-flow:use-cases` markers, a generated table
+with the identifier, use case, actors, package, requirement, links to the three
+realization cards and the status. Below it are the use-case diagrams: one general
+diagram, and one per actor when there are several. `RUP index` regenerates all of it
+after a card's front matter changes, and `check` warns when it is stale.
+
+## Front matter that drives the diagrams
+
+| Key | Effect |
+| --- | --- |
+| `actor` | Comma separated; each actor is drawn outside the system boundary |
+| `package` | Groups related use cases inside the boundary |
+| `includes`, `extends` | Drawn as `<>` and `<>` relations |
+
+An actor is linked only to the use cases that no other use case of that actor includes,
+as is usual in use-case diagrams.
+
+## Checklist before marking `reviewed`
+
+- The main flow reaches the goal and each step has a system response.
+- Failure and alternative paths exist for each input and precondition.
+- Entities, attributes and rules referenced exist in the domain model.
+- The wireframes cover the fields of the flow.
+- The row exists in the traceability table.
diff --git a/docs/pro/versions.md b/docs/pro/versions.md
new file mode 100644
index 0000000..d569c3c
--- /dev/null
+++ b/docs/pro/versions.md
@@ -0,0 +1,59 @@
+---
+title: Pro versions and compatibility
+description: The Pro changelog, which free version each Pro release contains and how pages here say since which Pro version they apply.
+edition: pro
+since: "1.0"
+---
+
+# Pro versions and compatibility
+
+rup-flow Pro has its own version. Every Pro package contains a complete copy of the free
+skill and states which one:
+
+```console
+RUP version
+rup-flow Pro 1.0.0 (built on rup-flow free 1.0.0)
+```
+
+## Compatibility
+
+| Pro | Contains free | Documentation line |
+| --- | --- | --- |
+| 1.0.x | 1.0.x | 1.0 |
+
+The documentation line is the free edition's `MAJOR.MINOR`; a Pro release is documented
+on the line of the free version it contains. Pages and rows marked
+Pro carry a `since` version when a capability arrived
+after Pro 1.0.
+
+## Pro changelog
+
+### 1.0.0
+
+First release of rup-flow Pro, built on rup-flow free 1.0.0.
+
+- The complete documentation set: ranked domain model, entity lifecycles, use-case
+ diagrams (general and per actor), wireframes, analysis collaborations, design classes,
+ sequences, data model, components, deployment, implementation cards, code map, project
+ profile, traceability, audit and decision records.
+- Code to RUP with `scan`, RUP to code with trace links, drift detection and the audit.
+- Eight palettes, custom colors and fonts, Mermaid, PNG previews and the interactive
+ explorer with its overview, relation tracing and exports.
+- The `rup-architect` and `rup-reviewer` subagents.
+- The stack pack `nestjs-prisma` and the domain library `lms`.
+- A complete example project.
+- The `version` command, which reports the Pro version and the free version it contains.
+
+## How releases are identified
+
+| Edition | Tag | Package |
+| --- | --- | --- |
+| Free | `vMAJOR.MINOR.PATCH` | `rup-flow-free-.zip` |
+| Pro | `pro-vMAJOR.MINOR.PATCH` | `rup-flow-pro-.zip` |
+
+The version in the file name is the version `RUP version` prints, and the one in
+`SKILL.md` metadata.
+
+## Related
+
+[Versioning and URLs](../releases/versioning.md) · [Update rup-flow](../releases/updating.md)
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 9d48ee6..a41b0a2 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -1,32 +1,40 @@
---
title: Command line
-description: Every command and flag of the free rup-flow CLI.
+description: Every command and flag of the rup-flow CLI, free and Pro.
---
# Command line
Run the CLI from the project root. `RUP` below stands for
-`node /scripts/rup.mjs`, where `` is the folder that
-contains `SKILL.md`.
+`node /scripts/rup.mjs`, where `` is the folder that contains
+`SKILL.md`.
```console
RUP [arguments] [flags]
```
+Commands and flags marked Pro exist only in the Pro
+edition. In the free edition they stop with a message that names Pro and exit with
+code `1`.
+
## Commands
-| Command | Effect |
-| --- | --- |
-| `init` | Create `rup.config.json` and the documentation skeleton. Never overwrites a file. |
-| `new use-case ` | Scaffold the requirements card and the specification diagram of a use case, then refresh the index. |
-| `index` | Regenerate the use-case index table from the cards. |
-| `render` | Draw every `.puml` source into a `.svg` through the PlantUML server. |
-| `check` | Verify structure, links and diagrams. |
-| `editions` | Print what the free edition includes and what is part of Pro. |
-| `instructions --target ` | Add or refresh the rup-flow block in an agent instruction file. |
-| `server up` / `server down` | Start or stop the PlantUML container. |
-| `health` | Verify that the PlantUML server renders. |
-| `config` | Print the resolved configuration. |
+| Command | Edition | Effect |
+| --- | --- | --- |
+| `init` | Free | Create `rup.config.json` and the documentation skeleton. Never overwrites a file. |
+| `new use-case ` | Free | Scaffold the cards of a use case, then refresh the index. Free: requirements card and specification. Pro: also analysis, design and implementation cards, wireframes, collaboration and sequence. |
+| `index` | Free | Regenerate the use-case index from the cards. Pro: also the use-case diagrams. |
+| `render` | Free | Draw every `.puml` source into a `.svg` through the PlantUML server. Pro: themed, plus Mermaid and PNG. |
+| `check` | Free | Verify structure, links and diagrams. Pro: also traceability and realization checks. |
+| `editions` | Free | Print the catalogue and what the installation includes. |
+| `version` | Free | Print the edition and version, `--json` for machines. |
+| `instructions --target ` | Free | Add or refresh the rup-flow block in an agent instruction file. |
+| `server up` / `server down` | Free | Start or stop the PlantUML container. |
+| `health` | Free | Verify that the PlantUML server renders. |
+| `config` | Free | Print the resolved configuration. |
+| `explore` | Pro | Build `explorer.html`, the interactive viewer of every diagram. |
+| `themes` | Pro | List the palettes, `--json` for machines. |
+| `scan` | Pro | Inventory of the code base, the input of code to RUP. |
Without a command the CLI prints its usage.
@@ -38,17 +46,30 @@ Without a command the CLI prints its usage.
| `--out ` | Documentation directory, relative to the root (overrides `outDir`). |
| `--lang ` | Language of the documents (overrides `docLanguage`). |
| `--project ` | Project name used in titles. |
+| `--code-root ` | Where the code lives (overrides `codeRoot`). |
| `--plantuml-url ` | Address of the PlantUML server. |
| `--force` | Redraw diagrams that are up to date. |
+## Pro flags Pro
+
+| Flag | Meaning |
+| --- | --- |
+| `--theme ` | Palette: `default`, `ocean`, `forest`, `sunset`, `grape`, `mono`, `dark` or `high-contrast`. |
+| `--color- "#RRGGBB"` | Override one color: `background`, `text`, `line`, `border`, `primary`, `secondary`, `accent` or `note`. |
+| `--font `, `--font-size ` | Font family and size of the diagrams. |
+| `--diagram-language plantuml\|mermaid` | Language of the diagram sources. |
+| `--outputs svg,png,html` | What `render` produces: SVG, PNG previews, the explorer. |
+| `--preview-png` | Add PNG previews to the outputs. |
+
## `init`
```console
RUP init --out docs/rup --lang es --project shop
```
-Creates the configuration and the free skeleton. Files that exist are skipped.
-The report lists what was created and how many artifacts are available in Pro.
+Creates the configuration and the skeleton. Files that exist are skipped. The report
+lists what was created; in the free edition it also says how many artifacts are
+available in Pro.
## `new use-case`
@@ -65,8 +86,11 @@ RUP new use-case createOrder --title "Create order" --actor Customer --package O
| `--requirement ` | Requirement identifier. Defaults to `RF-001`. |
| `--includes `, `--extends ` | Names of related use cases. |
| `--id ` | Force the identifier instead of the next free one. |
+| `--discipline ` Pro | Which cards to create: `requirements,analysis,design,implementation`. |
The name must be camelCase made of letters and digits. The command fails otherwise.
+Pro also adds the row of the use case to the
+traceability table.
## `render`
@@ -79,20 +103,50 @@ RUP render --path docs/rup/00-domain-model --force
| `--path ` | Render only this directory. |
| `--force` | Redraw everything. |
-Exit code is `1` when any diagram fails.
+A change of palette redraws everything automatically. The exit code is `1` when any
+diagram fails.
## `check`
-`--strict` makes warnings fail the command. Without it, only errors do.
+`--strict` makes warnings fail the command. Without it, only errors do. What it
+reports is listed in [Render and check diagrams](../guides/render-and-check.md).
+
+## `explore` Pro
+
+Writes `explorer.html` in the documentation directory: one file, no server, no
+network. Use `--outputs svg,html` to build it after every `render`. The features are
+in [The interactive explorer](../pro/explorer.md).
+
+## `scan` Pro
+
+```console
+RUP scan --code-root src --write
+```
+
+Prints, or with `--write` saves as `04-implementation/code-inventory.json`, the
+extensions, manifests and the candidate entities, entry points, services,
+persistence, tests and contracts of the code. `--limit ` caps each sample (60 by
+default). The agent reads it to start [code to RUP](../pro/code-to-rup.md).
## `instructions`
```console
-RUP instructions --target agents,claude,gemini,copilot,cursor
+RUP instructions --target agents,claude,gemini
+```
+
+Without `--target` it lists the targets. `--skill-path ` sets where the block
+says the skill lives. All targets are in [Compatible agents](../getting-started/compatible-agents.md).
+
+## `version` and `editions`
+
+```console
+RUP version
+RUP editions --json
```
-Without `--target` it lists the targets. `--skill-path ` sets where the
-block says the skill lives.
+`version` prints `rup-flow free 1.0.0`, or for Pro `rup-flow Pro 1.0.0 (built on
+rup-flow free 1.0.0)`. With `--json` it prints the edition and versions as JSON.
+`editions` prints the catalogue as a checklist of what the installation includes.
## `server`
@@ -104,10 +158,3 @@ Needs Docker with Compose. The port comes from `plantuml.url`.
| --- | --- |
| `0` | Done. |
| `1` | A check failed, a render failed, or the command stopped (invalid input, missing server, a capability that is part of Pro). |
-
-## Capabilities that are part of Pro
-
-These flags and commands stop with a message that names Pro and its address:
-`themes`, `explore`, `scan`, `--theme`, `--font`, `--font-size`, `--color-*`,
-`--preview-png`, `--outputs` with `png` or `html`, and `--diagram-language
-mermaid`. See [Free and Pro compared](../pro/compare.md).
diff --git a/docs/reference/folder-structure.md b/docs/reference/folder-structure.md
index a57a87c..c78fa67 100644
--- a/docs/reference/folder-structure.md
+++ b/docs/reference/folder-structure.md
@@ -1,10 +1,12 @@
---
title: Folder structure
-description: The default tree the free edition generates and the purpose of each folder.
+description: The tree each edition generates and the purpose of each folder.
---
# Folder structure
+## Free edition
+
```text
/ default docs/rup
├── README.md index
@@ -25,8 +27,55 @@ description: The default tree the free edition generates and the purpose of each
└── open-questions.md
```
-A use case is named in camelCase (`createOrder`) and keeps that name as its
-folder.
+A use case is named in camelCase (`createOrder`) and keeps that name as its folder.
+
+## Pro edition Pro
+
+Pro writes the same tree and fills in the rest. New or fuller entries are marked.
+
+```text
+/
+├── README.md index of the six disciplines
+├── 00-domain-model/
+│ ├── README.md levels of importance, dictionary, rules
+│ ├── domain-model.puml/.svg ranked model, attributes, multiplicities (Pro)
+│ ├── domain-model-simple.puml/.svg
+│ └── entity-states/ lifecycle of entities (Pro)
+├── 01-requirements/
+│ ├── README.md use-case index and diagrams
+│ ├── use-case-overview.puml/.svg general use-case diagram (Pro)
+│ ├── use-cases-.puml/.svg one per actor when there are several (Pro)
+│ ├── actors.md
+│ ├── requirements.md
+│ └── use-cases//
+│ ├── README.md
+│ ├── specification.puml/.svg
+│ └── wireframes.puml/.svg interface prototype (Pro)
+├── 02-analysis/
+│ ├── README.md
+│ ├── class-diagram.puml/.svg
+│ └── use-cases// analysis card and collaboration (Pro)
+├── 03-design/ (Pro)
+│ ├── README.md
+│ ├── class-diagram.puml/.svg
+│ ├── project-configuration.md
+│ ├── data-model/, components/, deployment/
+│ └── use-cases// design card and sequence
+├── 04-implementation/ (Pro)
+│ ├── README.md
+│ ├── code-map.md model element to code location
+│ ├── code-inventory.json from `scan --write`
+│ └── use-cases//README.md code and tests of one use case
+└── 05-quality/
+ ├── project-profile.md objective, constraints, stack (Pro)
+ ├── traceability.csv requirement to code and test (Pro)
+ ├── open-questions.md
+ ├── audit.md findings with evidence (Pro)
+ └── decisions/DEC-001-*.md decision records (Pro)
+```
+
+The numbering is kept in both editions, so a project moves to Pro without renaming
+anything. See [The complete documentation set](../pro/documentation-set.md).
## What each folder is for
@@ -35,17 +84,12 @@ folder.
| `00-domain-model` | The business concepts, their definitions and the rules that constrain them |
| `01-requirements` | Who uses the system, what it must do, and each use case as a card plus a specification |
| `02-analysis` | The first software structure: boundary, control and entity classes |
-| `05-quality` | What is still unknown |
-
-## Folders created by Pro
-
-`03-design` and `04-implementation` do not exist in the free edition, and
-`05-quality` gains the project profile, traceability table, audit and decision
-records. The numbering is kept so a project can move to Pro without renaming
-anything. See [The complete documentation set](../pro/documentation-set.md).
+| `03-design` Pro | Design classes, sequences, data model, components, deployment |
+| `04-implementation` Pro | Where each model element lives in code, and its tests |
+| `05-quality` | What is unknown (free); profile, traceability, audits and decisions (Pro) |
## Sources and renders
-Every diagram is a `.puml` source with its `.svg` next to it. Markdown links to
-the SVG with a relative path. `.rup-render-state.json` in the documentation
-directory records the last render so unchanged diagrams are skipped.
+Every diagram is a `.puml` source with its `.svg` next to it. Markdown links to the
+SVG with a relative path. `.rup-render-state.json` in the documentation directory
+records the last render so unchanged diagrams are skipped.
diff --git a/docs/reference/index.md b/docs/reference/index.md
index fc2e3cc..ff6a611 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -1,6 +1,6 @@
---
title: Reference
-description: Exact behaviour of the rup-flow command line, configuration, folder structure, identifiers and provenance marks.
+description: Exact behaviour of the rup-flow command line, configuration, folder structure, identifiers and provenance marks, free and Pro.
---
# Reference
@@ -57,4 +57,14 @@ Confirmed, observed, assumed and open.
+
+
+## Free and Pro compared
+
+Every capability, marked free or Pro.
+
+[Read the catalogue](../pro/compare.md)
+
+
+
diff --git a/docs/reference/provenance.md b/docs/reference/provenance.md
index 495ffea..802c983 100644
--- a/docs/reference/provenance.md
+++ b/docs/reference/provenance.md
@@ -32,7 +32,7 @@ what they block.
**Observed** claims need code, which is the job of the code-to-RUP workflow in
-[rup-flow Pro](../pro/code.md). In the free edition, statements are confirmed,
+[rup-flow Pro](../pro/code-to-rup.md). In the free edition, statements are confirmed,
assumed or open.
diff --git a/docs/releases/changelog.md b/docs/releases/changelog.md
index 5ab8286..fcaf189 100644
--- a/docs/releases/changelog.md
+++ b/docs/releases/changelog.md
@@ -1,125 +1,23 @@
---
title: Changelog
-description: Changes of the free rup-flow skill, release by release.
+description: Changes of the free rup-flow skill, release by release. The Pro changelog is in the Pro section.
---
# Changelog
-Changes of the free skill. The format follows [Keep a Changelog](https://keepachangelog.com/) and the project uses [Semantic Versioning](https://semver.org/).
+Changes of the free skill. The format follows [Keep a Changelog](https://keepachangelog.com/) and the project uses [Semantic Versioning](https://semver.org/). Pro releases are in the [Pro changelog](../pro/versions.md).
## Unreleased
-## 0.4.0
+## 1.0.0
-rup-flow becomes a free edition plus a paid one. This repository now holds the free edition; **rup-flow Pro** is a separate private product that extends it. Releases up to 0.3.3 remain available under the MIT license they were published with.
+First release of the free edition from a clean history. It turns requirements into a basic RUP documentation set with PlantUML diagrams for any coding agent.
### Added
-- `editions` command and `editions.json`: a catalogue of every diagram, document, workflow and tool, marked free or Pro.
-- An extension point: when `scripts/pro/index.mjs` is installed next to the CLI, the CLI loads it; the free edition runs without it.
-- The full user documentation is now a versioned site, .
-
-### Changed
-
-- The free edition keeps the simplified domain model, actors, requirements, the use-case requirements card with its specification statechart, the analysis classes and the open-questions list, rendered with PlantUML in its default look.
-- Generated documents and CLI output point to Pro where a capability is not included.
-- The documentation moved from the GitHub documentation to the documentation site; the documentation is disabled.
-
-### Removed (now part of rup-flow Pro)
-
-- Themes, palettes, colors and fonts; Mermaid; PNG previews; the interactive explorer.
-- The ranked domain model, entity lifecycles, use-case diagrams, wireframes, collaborations, design, implementation, quality and traceability artifacts.
-- Code to RUP (`scan`), RUP to code, drift detection, audit, and the `rup-architect` and `rup-reviewer` subagents.
-
-## 0.3.3
-
-### Added
-
-- The generated `claude-plugin` branch carries a square 512 px icon at `.claude-plugin/icon.png`, which the plugin directory asks for. It is drawn by the same code as the SVG icon and exists only in that branch; `main` still has no binary files.
-
-### Changed
-
-- The CLI help describes the four cards of a use case, and CONTRIBUTING.md documents the repository branches.
-
-## 0.3.2
-
-### Changed
-
-- The plugin is published from its own branch, `claude-plugin`, generated on every release tag. It holds only the skill, the two agents and the manifests, so the directory scan no longer reads the installer, tests, workflows or tooling. The repository marketplace installs from that branch. New `tools/build-plugin.mjs` and a publish workflow, with tests.
-
-## 0.3.1
-
-### Changed
-
-- Removed every name and mechanism the directory scan reads as sensitive data leaving the machine: a variable in the SVG parser, and the release workflow, which now publishes through the official script action with its logic in a tested module. Validation fails if such names or environment reads appear in code, workflows or manifests.
-
-## 0.3.0
-
-### Added
-
-- One card per discipline for every use case (requirements, analysis, design, implementation and tests), each starting with the same navigation table, plus the implementation card with code and tests tables.
-- `index` command and generated block in the requirements README: use-case table with links to every discipline, the general use-case diagram (actors outside the system boundary, use cases grouped in packages, `include` and `extend`) and one diagram per actor. `new use-case` takes `--package`, `--goal`, `--includes` and `--extends`; `check` warns when the index is stale.
-- Component diagram template (PlantUML and Mermaid) and its section in the design README.
-- Explorer: global search across the text of every diagram, grouping by discipline or by use case, previous and next navigation, links between the diagrams of one use case, a Document tab that renders the cards and follows their links, relation tracing with direct or all-reachable depth, PNG and SVG export, copy source and link, full screen, keyboard shortcuts and richer deep links.
-
-### Changed
-
-- The example shop now has four use cases in two packages and two actors, and a component diagram.
-
-## 0.2.0
-
-### Changed
-
-- The user documentation moved to the GitHub documentation; the README is now a short pitch with install steps that links to it. The repository keeps only the gallery images.
-
-## 0.1.5
-
-### Changed
-
-- Removed the gallery browser option and turned the repository commands in AGENTS.md into npm scripts, the last two texts the directory scan read as a credential leaving the machine.
-
-## 0.1.4
-
-### Changed
-
-- Renamed identifiers and literals that the directory scan misread as credential handling (variables named key, the SVG namespace URL, the --chrome option).
-
-## 0.1.3
-
-### Changed
-
-- The plugin tree has no binary files, no `process.env` reads and no listing-only fields in `plugin.json`, so the directory scan has nothing to report: the icon PNG and explorer screenshots moved to the `docs-assets` branch, the icon and URLs are set in the submission portal, the CLI reads only flags and `rup.config.json`, PlantUML requests live in their own module, and the release workflow no longer runs Node. Validation enforces these rules. Added PRIVACY.md.
-
-## 0.1.2
-
-### Changed
-
-- Compatibility table: Codex and Gemini CLI are marked as tested by the maintainer; Cursor and Copilot remain untested.
-
-## 0.1.1
-
-### Added
-
-- Portable across agents: `install.mjs --target claude|agents|codex|all` (installs into `.claude` or the `.agents/skills` location used by Codex and similar clients) and `rup.mjs instructions --target ...` (marked, idempotent blocks for `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot and Cursor).
-- `AGENTS.md` for agents working on the repository, `docs/other-agents.md` with a compatibility table, and `docs/architecture.md` with the layers and how to add a client.
-- `SKILL.md` frontmatter now carries `license`, `compatibility` and `metadata`, and validation enforces the Agent Skills naming rules and a single version across files.
-
-### Fixed
-
-- Directory validation holds that were avoidable: the Docker server command no longer forwards the whole environment, CI waits for the server through the CLI instead of `curl`, and gallery SVGs have short path lines.
-- Release title is the tag alone, and a deleted release can be recreated from its tag with `workflow_dispatch`.
-
-## 0.1.0
-
-### Added
-
-- `rup-flow` skill: requirements → RUP, code → RUP, RUP → code, sync and audit workflows.
-- Fixed documentation structure with configurable output directory, folder names, language and identifier prefixes.
-- CLI (`init`, `new use-case`, `scan`, `render`, `check`, `server`, `health`, `config`) with no dependencies.
-- PlantUML rendering to SVG through a Docker server (sandbox profile, loopback only).
-- Mermaid as an alternative diagram language (`diagrams.language`), rendered by a pinned mermaid-cli container.
-- Eight color presets plus custom palettes, fonts and level colors (`theme`), applied at render time.
-- `diagrams.outputs`: `svg`, `png` previews and an interactive `explorer.html` (pan, zoom, search, relation highlighting, source, dark view, deep links).
-- `explore` and `themes` commands; `tools/build-gallery.mjs` regenerates the documentation images.
-- Agents `rup-architect` and `rup-reviewer`.
-- Claude Code plugin and marketplace manifests, installer, web ZIP packaging and icon generator.
+- The simplified domain model, actors, requirements, the use-case requirements card with its specification statechart, the analysis classes and the open-questions list.
+- The CLI: `init`, `new use-case`, `index`, `render`, `check`, `instructions`, `server`, `health`, `config`, `editions` and `version`.
+- `editions.json`: a catalogue of every diagram, document, workflow and tool, marked free or Pro. The CLI loads `scripts/pro/index.mjs` when it exists next to it and stops with a message that names Pro for anything outside the edition.
+- Instruction targets for fifteen kinds of agent: AGENTS.md, Claude, Gemini, Copilot, Cursor, Windsurf, Cline, Roo Code, Kilo Code, Continue, JetBrains Junie, Amazon Q Developer, Zed, Aider and a portable file for any agent with a shell.
+- `install.mjs --dir ` installs the skill into the skills folder of any client.
+- Versioned release packages: `rup-flow-free-.zip`.
diff --git a/docs/releases/index.md b/docs/releases/index.md
index 31b0a37..32bca5e 100644
--- a/docs/releases/index.md
+++ b/docs/releases/index.md
@@ -1,15 +1,16 @@
---
title: Releases
-description: Choose the correct rup-flow documentation, understand compatibility and trace immutable releases.
-application_line: "0.4"
-validated_application_version: "0.4.0"
+description: Choose the correct rup-flow documentation, understand how the free and Pro versions map and trace immutable releases.
+application_line: "1.0"
+validated_application_version: "1.0.0"
---
# Releases
-This site documents the rup-flow `0.4` release line. The version selector uses
-`MAJOR.MINOR`; exact patches appear in the changelog. Separate immutable tags and
-GitHub releases identify each approved publication of these pages.
+This site documents the rup-flow `1.0` release line: the free edition `1.0.x` and the
+rup-flow Pro releases built on it. The version selector uses `MAJOR.MINOR`; exact patches
+appear in the changelogs. Separate immutable tags and GitHub releases identify each
+approved publication of these pages.
@@ -17,7 +18,7 @@ GitHub releases identify each approved publication of these pages.
## Match a version
-Understand skill versions, publication revisions, aliases and stable URLs.
+Understand edition versions, publication revisions, aliases and stable URLs.
[Read versioning and URLs](versioning.md)
@@ -27,9 +28,9 @@ Understand skill versions, publication revisions, aliases and stable URLs.
## Review changes
-Find the exact release that introduced a change.
+Find the exact release that introduced a change, free or Pro.
-[Read the changelog](changelog.md)
+[Free changelog](changelog.md) · [Pro changelog](../pro/versions.md)
@@ -45,13 +46,13 @@ Move to a new version without losing your documentation.
-## Two editions, two version lines
+## Two editions, two version numbers
-| Edition | Version line | Where its changes are recorded |
-| --- | --- | --- |
-| Free | `0.4.x` | [Changelog](changelog.md) |
-| Pro | `1.x`, built on a named free version | The Pro package and its listing |
+| Edition | Version line | Tag | Package |
+| --- | --- | --- | --- |
+| Free | `1.0.x` | `vMAJOR.MINOR.PATCH` | `rup-flow-free-.zip` |
+| Pro | `1.0.x`, built on a named free version | `pro-vMAJOR.MINOR.PATCH` | `rup-flow-pro-.zip` |
-This site follows the free edition's line. Pro states the free version it was
-built on, and every Pro page here describes capabilities that exist in that
-build.
+This site follows the free edition's line. A Pro release states the free version it
+contains (`RUP version`), and every Pro page here describes capabilities that exist in
+that build.
diff --git a/docs/releases/updating.md b/docs/releases/updating.md
index 9a525f9..4e9b3db 100644
--- a/docs/releases/updating.md
+++ b/docs/releases/updating.md
@@ -1,45 +1,38 @@
---
title: Update rup-flow
-description: Move to a newer rup-flow release without touching your documentation.
+description: Move to a newer rup-flow release, free or Pro, without touching your documentation.
---
# Update rup-flow
-Your documentation and `rup.config.json` live in your project. The skill lives in
-its own folder, so updating it never rewrites your documents.
+Your documentation and `rup.config.json` live in your project. The skill lives in its own
+folder, so updating it never rewrites your documents.
-## Claude Code
+## Steps
-```console
-claude plugin marketplace update rup-flow
-claude plugin update rup-flow@rup-flow
-```
+1. Read the changelog for the versions you skipped: [free](changelog.md) and, for Pro,
+ [Pro](../pro/versions.md).
+2. Download the new package, `rup-flow-free-.zip` or `rup-flow-pro-.zip`.
+3. Unzip it over the old skill folder, or replace the folder. Keep the same skills folder
+ your agent already reads.
+4. Run `RUP version` to confirm the version and `RUP check` on a project.
+5. Run `RUP index` once; the use-case index is regenerated from the cards.
-## Other clients
+On Claude on the web, upload the new ZIP in **Customize → Skills**.
-Run the installer again from an updated clone. It refuses to overwrite an
-existing install unless you pass `--force`, and it keeps a backup:
+## Agents that read an instruction file
+
+Run `instructions` again for each target. It replaces only the delimited block, so the
+rest of the file stays as you wrote it:
```console
-git pull
-node install.mjs --target agents --force
+RUP instructions --target cursor,windsurf
```
-## Claude on the web
-
-Upload the new `rup-flow-skill.zip` from the
-[latest release](https://github.com/hector-ae21/rup-flow/releases/latest).
-
-## After updating
-
-1. Read the [changelog](changelog.md) for the versions you skipped.
-2. Run `check` on a project.
-3. Run `index` once; the use-case index is regenerated from the cards.
-
-## Between 0.3 and 0.4
+## From the 0.x releases
-Version 0.4 split the project into a free edition and rup-flow Pro. If you used
-themes, Mermaid, the explorer, code scanning, design, implementation or
-traceability artifacts with 0.3, those are part of Pro now. Files you already
-generated stay in your project; the free `check` keeps working on them. Releases
-up to 0.3.3 remain available under the MIT license they were published with.
+Earlier releases of rup-flow were distributed differently and included features that are
+now part of rup-flow Pro: themes, Mermaid, the explorer, code scanning, design,
+implementation and traceability artifacts. Version 1.0 starts a clean line with two
+editions. Files you generated before stay in your project and the free `check` keeps
+working on them; to keep producing those artifacts, use rup-flow Pro.
diff --git a/docs/releases/versioning.md b/docs/releases/versioning.md
index 59deea1..76a9fb0 100644
--- a/docs/releases/versioning.md
+++ b/docs/releases/versioning.md
@@ -1,29 +1,50 @@
---
title: Versioning and URLs
-description: Match a rup-flow skill to its MAJOR.MINOR documentation line and audit immutable publication revisions.
+description: Match a rup-flow package, free or Pro, to its MAJOR.MINOR documentation line and audit immutable publication revisions.
---
# Versioning and URLs
-Skill versions, documentation lines and publication revisions answer different
-questions:
+Four numbers answer four different questions:
-- **Skill version:** which exact release of the skill is installed?
+- **Free version:** which release of the free skill is installed?
+- **Pro version:** which release of rup-flow Pro, and which free version does it contain?
- **Documentation line:** which compatible `MAJOR.MINOR` contract describes it?
-- **Publication revision:** which approved snapshot of these pages produced the
- current wording and images?
+- **Publication revision:** which approved snapshot of these pages produced the current
+ wording and images?
+
+## Reading your own version
+
+```console
+RUP version
+rup-flow free 1.0.0
+
+RUP version
+rup-flow Pro 1.0.0 (built on rup-flow free 1.0.0)
+```
+
+The same number is in the name of the package, `rup-flow-free-1.0.0.zip` or
+`rup-flow-pro-1.0.0.zip`, and in the `metadata.version` of `SKILL.md`.
+
+## How the editions map
+
+| Pro | Contains free | Read the docs of line |
+| --- | --- | --- |
+| 1.0.x | 1.0.x | 1.0 |
+
+A Pro release is documented on the line of the free version it contains. Pro pages carry
+the Pro version since which a capability exists, so one site covers both editions.
## MAJOR.MINOR controls the site
-The version selector and the canonical address use the skill's `MAJOR.MINOR`.
-Compatible patches update the same line instead of creating a new copy of the
-site.
+The version selector and the canonical address use the free edition's `MAJOR.MINOR`.
+Compatible patches update the same line instead of creating a new copy of the site.
```text
-Skill line: 0.4.x
-Validated skill: 0.4.0
-Version selector: 0.4
-Canonical path: /rup-flow-docs/0.4/
+Edition line: 1.0.x
+Validated version: 1.0.0
+Version selector: 1.0
+Canonical path: /rup-flow-docs/1.0/
```
## Aliases
@@ -37,15 +58,5 @@ The site root redirects to `latest`.
## Publication revisions
-Each approved publication of these pages gets an immutable tag and a GitHub
-release. A later editorial fix is a new revision in the same line; it never
-rewrites an earlier one.
-
-## Which version do I have?
-
-```console
-node scripts/rup.mjs config
-```
-
-does not print the version; read `metadata.version` in `SKILL.md`, or the
-`version` of the plugin manifest.
+Each approved publication of these pages gets an immutable tag and a GitHub release. A later
+editorial fix is a new revision in the same line; it never rewrites an earlier one.
diff --git a/mkdocs.yml b/mkdocs.yml
index 00b1725..94aaee1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,5 +1,5 @@
site_name: rup-flow
-site_description: Turn requirements into RUP documentation and code with your AI coding agent
+site_description: Turn requirements into RUP documentation and code with any AI coding agent
site_author: Hector Arrechea
site_url: &documentation_root https://hector-ae21.github.io/rup-flow-docs/
repo_name: hector-ae21/rup-flow-docs
@@ -104,6 +104,7 @@ nav:
- Get started:
- Get started overview: getting-started/index.md
- Install rup-flow: getting-started/installation.md
+ - Compatible agents: getting-started/compatible-agents.md
- Document your first system: getting-started/first-documentation.md
- How it works: getting-started/how-it-works.md
- Guides:
@@ -111,7 +112,6 @@ nav:
- Document a system: guides/document-a-system.md
- Add and change use cases: guides/use-cases.md
- Render and check diagrams: guides/render-and-check.md
- - Use another agent: guides/other-agents.md
- Troubleshooting: guides/troubleshooting.md
- Reference:
- Reference overview: reference/index.md
@@ -128,17 +128,35 @@ nav:
- Conventions: diagrams/conventions.md
- Architecture:
- Architecture overview: architecture/index.md
+ - Structure: architecture/structure.md
+ - Runtime behaviour: architecture/behavior.md
- Editions and the extension point: architecture/editions.md
- Trust and data flow: architecture/trust-and-data.md
+ - Quality and decisions: architecture/decisions.md
- Delivery and branches: architecture/delivery.md
- rup-flow Pro:
- Pro overview: pro/index.md
- Free and Pro compared: pro/compare.md
- - The complete documentation set: pro/documentation-set.md
- - Code in both directions: pro/code.md
- - Themes, Mermaid and the explorer: pro/themes-and-explorer.md
- - Packs, libraries and subagents: pro/packs-and-agents.md
+ - Documentation:
+ - The complete documentation set: pro/documentation-set.md
+ - Use-case cards: pro/use-case-cards.md
+ - Domain model diagrams: pro/diagrams-domain.md
+ - Requirements diagrams: pro/diagrams-requirements.md
+ - Analysis and design diagrams: pro/diagrams-design.md
+ - Code:
+ - Code to RUP: pro/code-to-rup.md
+ - RUP to code: pro/rup-to-code.md
+ - Sync and audit: pro/sync-and-audit.md
+ - Look and navigation:
+ - Themes: pro/themes.md
+ - Mermaid and PNG previews: pro/mermaid.md
+ - The interactive explorer: pro/explorer.md
+ - Extras:
+ - Stack packs: pro/packs.md
+ - Domain libraries: pro/domain-libraries.md
+ - Subagents: pro/subagents.md
- Get Pro: pro/get-pro.md
+ - Pro versions and compatibility: pro/versions.md
- License and support: pro/license-and-support.md
- Releases:
- Release overview: releases/index.md
diff --git a/overrides/main.html b/overrides/main.html
index fad95ef..b43d780 100644
--- a/overrides/main.html
+++ b/overrides/main.html
@@ -6,3 +6,17 @@
Open the current documentation.
{% endblock %}
+
+{% block content %}
+ {% if page and page.meta and page.meta.edition == "pro" %}
+
+ Pro
+
+ This page describes rup-flow Pro{% if page.meta.since %}, available since Pro {{ page.meta.since }}{% endif %}.
+ The free edition does not include it.
+ What Pro is
+
+