Blueprints is a desktop application for planning releases in signed local files. The main workspace is a hands-on blueprint board: versions contain work moving through a lifecycle, while dependency and release-note views project the same trusted documents for different tasks.
- Local workspace: the editable copy on this computer.
- Shared sync root: a separate directory used to exchange signed files. It may be on a local disk, network share, or another synchronized location.
- Identity: a local Ed25519 key pair and display name used to sign project data.
- Trust: whether required files and signatures validate.
- Version: a planned release in one of four states: Planned, In Progress, Frozen, or Released.
- Item: one release-plan entry with an item key, lifecycle state, type, changelog category, title, and completion state.
- Start Blueprints.
- Enter a project name and short code.
- Keep
SemVeror enter the versioning scheme your project uses. - Use Browse to choose different local and shared roots. Neither may contain the other.
- Select Create signed project.
Before creating or joining a project, enter the display name teammates should see and select Create identity. Blueprints creates protected local Ed25519 key material. Back up the complete Blueprints application-data directory before relying on that identity.
A new teammate can export a signed identity invitation directly from the setup screen before they belong to any project.
- Enter a version name in the compact toolbar and select + Version.
- Select the version frame to edit its name, release state, and accomplishment notes in Details.
- Select + Work item, choose Planned, In Progress, Review, or Complete, then enter type, changelog category, title, and context.
- Drag a work card horizontally into another lifecycle column, or use Left/Right while the card is selected.
- Move a version by its header, resize it from the lower-right handle, or collapse it when concentrating elsewhere.
- Use search, version/lifecycle filters, Focus, Selection, Fit view, and the clickable minimap on larger plans.
Containment is the ownership cue in Plan, so Blueprints does not draw a line from every version to every item. Changelog category stays visible as a badge and remains authoritative for release-note export. Released and Frozen versions remain immutable.
- Plan: the default interactive version-frame and lifecycle-column board.
- Dependencies: a graph layout that emphasizes typed relationships, direction, and labels.
- Release Notes: a cleaned category projection for reviewing changelog structure.
- Timeline: visibly unavailable until Blueprints has a signed target-date contract; no dates are inferred.
View mode, search, filters, focus, collapsed frames, minimap visibility, zoom, and viewport are local presentation preferences. They do not modify project documents or create collaboration conflicts.
Use Connect in the toolbar when containment is not enough:
- Define at least one relationship type in the Relationships inspector tab, including whether it is directional.
- Select Connect, then choose the visible handle on two entities.
- Review the populated source, target, type, and optional label in the compact relationship editor.
- Select Save to commit, or change the fields before saving.
- Select an edge to edit or remove it. Hover or select an edge to reveal its type/label.
Directional types draw arrowheads and every type uses its configured color. Selecting a node highlights incoming/outgoing links and dims unrelated edges. Definitions and endpoints are signed shared project state, so changes participate in audit, push, pull, trust checks, duplicate/self-link validation, and whole-document conflict resolution. Connection mode is disabled when the workspace cannot mutate.
- Dragging a node saves the arrangement when the pointer is released.
- Middle-drag empty canvas space to pan.
- Scrolling saves the viewport locally after a short pause.
- Use Ctrl+mouse wheel or Ctrl+plus/minus to zoom; zoom is remembered locally for this workspace.
- Ctrl+S saves shared node positions and Ctrl+0 fits the local view.
- Fit view returns to the standard overview without rearranging nodes.
- Auto arrange deliberately replaces positions with deterministic defaults.
- Save layout explicitly writes the current arrangement.
- Undo and redo restore node drags or auto-arrangement changes made during the current session. Use the toolbar,
Ctrl+Z,Ctrl+Shift+Z, orCtrl+Y.
The saved revision appears at the bottom of the inspector. Node positions are signed project state and participate in push, pull, trust validation, audit history, and conflicts. Undo and redo create new signed revisions instead of rewriting history, and their in-memory stack resets when the app session or graph structure changes. Zoom and scroll offsets stay machine-local so navigating does not create team conflicts. Older workspaces without a layout file use default positions until the first save.
See canvas engine for the exact model and troubleshooting for recovery.
- Select a version node.
- Open the Versions and releases tool from the rail.
- Choose whether to include incomplete items, item keys, descriptions, or compact output.
- Select Preview notes to review the exact Markdown without writing a file.
- Select Export notes and review the saved path.
Incomplete items are excluded by the current default rules. When a local Git repository is linked, recent commit subjects and matching item keys are added as source context.
Before freezing or releasing, review Release readiness in the release planner. It reports:
- an unavailable or unconfigured repository;
- uncommitted working-tree changes that make the source baseline unstable;
- incomplete items in the selected version;
- missing post-tag history;
- recent commits that do not reference a completed item key in the selected version.
- missing, risky, incomplete, stale, future-dated, or recent healthy VaultSync recovery evidence.
Repository errors and dirty state are blockers. Unmatched commits and incomplete items require attention because they may be intentionally out of scope; Blueprints explains them but does not silently change source history or the release plan.
VaultSync recovery evidence is advisory by default. Snapshot, backup, and verification reports are considered recent for seven days, with five minutes allowed for producer clock skew. Blueprints does not disable release merely because VaultSync is absent or needs attention.
Draft versions and items in Planned or In Progress state can be archived. Select the archive action twice to confirm. The entity leaves the active signed plan, its removal participates in sync, and its signed files remain under .blueprints/archive/ for recovery. Frozen and released versions are immutable and cannot be archived.
- Open Find work from the navigation.
- Select Browse… to choose an existing local repository, or enter a remote address and choose Clone and link repository.
- Select the linked repository. Use Pull latest, Commit all, or Push commits only when you intend that exact Git action.
- Select Find work to import.
- Review the proposal inbox produced from changelogs, roadmaps, GitHub/GitLab issues, changes, releases, and planning records.
- Edit the selected proposal’s title, context, target version, type, changelog group, and completion state.
- Exclude anything that should not enter Blueprints, then select Apply approved to blueprint.
Discovery remains read-only and never triggers the neighboring Git buttons. Proposals are not project data until Apply. Apply requires a trusted workspace, adds the reviewed proposals as signed work items, records their provenance, and writes one audit action.
Pull requires a clean worktree and accepts fast-forward updates only. Commit all stages every tracked, untracked, and deleted file, so inspect the repository first when only some changes belong together. Blueprints disables hooks and refuses repository-local executable filters, merge drivers, and file monitors for its Git write operations. It does not initialize submodules, force-push, rewrite history, or resolve merge conflicts.
Public GitHub issues, pull requests, and releases are read directly without requiring the GitHub CLI. For private repositories, draft releases, and GitHub Projects, start Blueprints with a read-only token in BLUEPRINTS_GITHUB_TOKEN. Blueprints reads that variable for the current process and does not store it in project or integration settings. Local changelog and roadmap discovery remains available when GitHub cannot be reached. See Source Lens for limits, duplicate behavior, and security details.
GitLab.com worktrees use the same flow for issues, merge requests, releases, and milestones. Public projects need no credential; private projects use a read-only BLUEPRINTS_GITLAB_TOKEN in the application environment. Nested GitLab group paths are supported.
Open Source Lens, then enter a VaultSync destination, .vaultsync directory, meta directory, or exact vaultsync.meta.db path in the VaultSync field and select Save health link.
Blueprints confirms the portable metadata store exists without reading its SQLite schema. If VaultSync also supplies .vaultsync/meta/blueprints.status.json, the connection card reports destination reachability, latest snapshot, backup and verification times, restore readiness, backup-index consistency, and metadata conflicts. A missing health document is shown honestly as “metadata detected; detailed backup health unavailable.”
This integration is passive and machine-local. Blueprints does not register or modify VaultSync projects, start a backup, verify payloads, or make VaultSync evidence authoritative. See VaultSync integration for the exact contract and limits.
To prepare the current trusted project for VaultSync transport, select Register exchange twice. The first selection previews the exact project-specific path; the second consumes a short-lived approval and creates the directory plus registration marker. Registration does not redirect the currently open project. Reopen it with the reported path as the shared root only when you intend to start using that exchange location.
The shared root is an exchange layer, not the editable workspace.
To add a second person:
- The new person opens Team in any local project and exports a signed identity invitation.
- An existing project administrator imports that file, reviews the requested display name and role, and adds the member.
- The administrator pushes the membership revision.
- With the new member selected, the administrator exports a signed project invitation.
- The new member chooses Join a team project on the setup screen and selects an empty local workspace.
- Blueprints stages and validates the shared project before promoting it to the chosen local location.
Project invitations are targeted to one local identity. Treat them as sensitive team coordination records and transfer them through an authenticated channel.
- Refresh comparison compares local, shared, and last-synced baselines.
- Push copies valid outgoing signed documents and updates the signed manifest.
- Pull validates incoming signatures and manifest continuity before applying changes.
- The exchange header reports the last locally recorded pulled/pushed manifest versions and successful trust check; these are local evidence, not a guarantee that an offline shared folder has not changed.
- If both copies changed, Blueprints blocks mutation until you choose Keep Local or Accept Shared.
The conflict view summarizes important fields for known project document types and keeps bounded raw previews available for diagnosis. Before applying Keep Local or Accept Shared, Blueprints preserves both available document/signature pairs under .blueprints/recovery/conflicts/ in the local workspace. The completion message includes the exact recovery directory.
Conflict recovery copies reduce the risk of an accidental choice, but they are not a substitute for backing up the complete workspace before important collaboration or membership changes.
Open Trust from the tool rail to see signature, audit, shared-folder, and conflict diagnostics.
- Trusted: normal editing is allowed.
- Untrusted: one or more signatures did not validate; mutation is disabled.
- Corrupt: required data or audit continuity is missing or malformed; mutation is disabled.
Do not “repair” a signature by deleting it or copying another signature file. Restore a known-good workspace or shared snapshot and re-open it.
Back up both:
- the chosen local workspace;
- the Blueprints application-data directory containing the identity and its protected key.
A workspace without the signing identity may remain readable but cannot be safely continued as the same member. Formal key recovery is not implemented yet.
See workspace format, security model, member key lifecycle, and backup and disaster recovery for details.