` then a one-sentence purpose. 2. A fenced `semaphore <group> --help` block. 3. An alias note as a `>` blockquote when the group has an alias (`> \`vault\` is an alias for \`vaults\`.`). 4. A subcommand table (`| Command | Purpose |`) with in-page anchor links when the page is long. 5. One `##` section per subcommand: a short description, a copy-pasteable example, then a `| Flag | Description |` table. State required/exactly-one rules in prose under the table. Conventions: - Internal links are absolute from the route base `/`: **`/reference/cli/<page>`** (NOT `/cli/<page>` — that base is wrong and 404s). Cross-links to concept pages use the same form, e.g. `/admin-guide/runners`, `/admin-guide/security/encryption`. - Admonitions use Docusaurus syntax: `:::tip`, `:::warning` … `:::`. - Keep prose task-oriented and match the tone/heading depth of neighboring pages. ## Index page (`cli.md`) and sidebar - `cli.md` carries: intro + `semaphore help`, a command-group table linking to each page, the **global options** table, and short sections for `version`, `setup`, `server`, `runner`, `migrate`. - Every command-group page must be registered in **`docs/sidebars.js`** under the `label: 'CLI'` category's `items` array, as `'reference/cli/<page>'`. Adding a page without registering it hides it from navigation. ## Workflow ### 1. Enumerate the live command tree Run the discovery greps above. Build the set of command groups and subcommands that actually exist. Note any group/subcommand/flag that has no corresponding doc section, and any doc section with no corresponding code. ### 2. Extract facts per command For each command, pull name, aliases, flags (name/default/usage), required/exclusive rules (from `Run`), and success output. Cross-check `*_test.go` for exact behavior. ### 3. Update each page Rewrite or patch each page so it matches the extracted facts and the page structure above. Add sections for new subcommands; remove sections for deleted ones; fix flag tables. Leave a page untouched only after confirming it already matches the code. ### 4. Update the index and sidebar Refresh `cli.md` (command table, global options, operational commands) and ensure every page is listed in `docs/sidebars.js`. ### 5. Build to catch broken links From the `docs/` directory: ```bash cd docs && npm run build 2>&1 | tail -40 ``` The build must end with `[SUCCESS] Generated static files`. **Broken-link** errors in pages you touched must be fixed. Pre-existing **broken-anchor** warnings in unrelated pages (e.g. `admin-guide/configuration`, `admin-guide/installation_manually`) are not yours to fix — note them and move on. If `node_modules` is absent, run `npm install` first (or tell the user the build couldn't run). ## Pitfalls - **Dead flags.** A flag registered in `init()` but never read in the command's `Run` does nothing — do not document it as functional. Example: after BoltDB removal, `migrate` still registers `--err-log-size`, `--skip-task-output`, `--merge-existing-users`, but `Run` only uses `--apply-to` / `--undo-to`. Verify each flag is actually consumed before documenting it. - **Removed features → version-gate, don't silently delete.** When a command/flag is removed (e.g. `migrate --from-boltdb`; BoltDB is "not supported starting from 2.19" per `cli/setup/setup.go`), keep the guidance but mark the version boundary with a `:::warning`, so users on older versions are still served. Note when other parts of the repo (e.g. `deployment/docker/server/server-wrapper`) still reference a removed flag — that's a stale call site worth flagging to the user, but out of scope for the docs change. - **Stale help strings.** A command's `Short`/`Long` text can lag the code. Verify config-key names against the actual structs in `util/` (e.g. `vault rekey`'s `--old-key` help says `access_key`, but the real config field is `secret_key` / `secret_key_file` in `util/config.go`). Document the struct, not the help string. - **Group commands have no flags of their own.** `users`, `projects`, `vaults`, `runner`, `token`, `totp` just print help and dispatch to subcommands. Don't invent flags for them. - **Don't document the internal `server` runtime.** `server.go`/`root.go` wire a lot of services; the doc only needs "start the server, `service` is an alias, respects global flags." ## When to ask or refuse - If a command's behavior is genuinely ambiguous from the code (e.g. a flag is read but its effect spans packages you can't quickly trace), summarize what you found and ask the user rather than guessing. - If asked to document a flag or command that **doesn't exist in `cli/cmd/`**, refuse and explain: CLI docs are generated from the Cobra code — add the command/flag first, then regenerate. - Before deleting a whole documented section (a removed command group), propose it explicitly; prefer version-gating over silent removal when older releases still ship the feature.  --- name: semaphore-commit --- Create well-formatted git commits following conventional commit standards. ## Behavior 1. Analyze staged changes with `git diff --staged` 2. Generate a conventional commit message 3. Create the commit with proper formatting 4. Do not add "Co-Authored-By: Claude ... <noreply@anthropic.com> to the footer" ## Commit Format ``` <type>(<scope>): <description> [optional body] [optional footer] ``` ## Types - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes - refactor: Code refactoring - test: Adding or modifying tests - chore: Maintenance tasks - agents: Changes related to AI agents work ## Example Output ``` feat(auth): add password reset functionality - Add forgot password form - Implement email verification flow - Add password reset endpoint ```  --- name: semaphore-config-schema description: > Generate or update the JSON Schema (in YAML form) that describes the Semaphore configuration file. The schema lives at `config.schema.yaml` in the repository root and is derived from the Go struct `util.ConfigType` (with nested types in `util/config.go`, `util/config_auth.go`, `util/App.go`, `util/OdbcProvider.go`). Use this skill whenever the user asks to "regenerate the config schema", "update config.schema.yaml", "sync the schema with ConfigType", "add a new field to the schema", "the schema is out of date", or after a Go struct change that affects configuration. Also trigger when the user adds a new top-level field, new nested struct, or changes a `json:`, `default:`, `rule:`, or `env:` tag on a config struct field. --- # Semaphore — Config Schema Generator This skill produces and maintains `config.schema.yaml` — a **JSON Schema draft 2020-12** document (written in YAML) describing every valid key in a Semaphore `config.json` / `config.yaml`. The schema is the source of truth for IDE autocomplete (via `yaml-language-server`) and for any future server-side config validation. The schema is **derived from Go code**, never hand-edited speculatively. If `ConfigType` doesn't have a field, the schema must not have it. If a field has a `default:` or `rule:` tag, the schema must reflect it. ## Inputs (source of truth) All Go types live in the `util` package. Read these files **in full** before writing anything: | File | What's in it | |------|--------------| | `util/config.go` | `ConfigType` (root) + most nested types: `DbConfig`, `TLSConfig`, `RunnerConfig`, `TotpConfig`, `EventLogType`, `TaskLogType`, `ConfigLog`, `SyslogConfig`, `ConfigProcess`, `ConfigAppNamespaces`, `ScheduleConfig`, `DebuggingConfig`, `HAConfig`, `HARedisConfig`, `TeamsConfig`, `ConfigDirs`, `SubscriptionConfig`, `LdapMappings`, `oidcEndpoint` | | `util/config_auth.go` | `MultifactorAuthConfig`, `EmailAuthConfig`, `TotpConfig`, `RecaptchaConfig` | | `util/App.go` | `App` | | `util/OdbcProvider.go` | `OidcProvider` (note: filename is `Odbc...`, typo'd — don't "fix" it) | If a struct moves or a new file appears, find it with: ```bash grep -rn "^type .* struct" util/ | grep -v _test ``` ## Output A single file: **`config.schema.yaml`** in the repository root. Header (top of file) — keep exactly this shape: ```yaml $schema: "https://json-schema.org/draft/2020-12/schema" $id: "https://semaphoreui.com/schemas/config.schema.json" title: Semaphore configuration description: Schema for Semaphore UI config.json / config.yaml. Generated from util.ConfigType. type: object ``` ## Field-mapping rules These are non-negotiable — apply them mechanically. ### Property name Use the **`json:` tag's first segment** (before any comma): ```go Port string `json:"port,omitempty" ...` // → property name "port" ``` Skip fields where the `json:` tag is `"-"` (e.g. `RunnerConfig.RegistrationToken`, `SubscriptionConfig.Key` — those are env-only, not file-configurable). Document this in the schema's `description` for the containing struct if a sensitive token is reachable only via env. Skip unexported fields (lowercase first letter) — but include their **referenced types** if they appear via exported fields. Example: `oidcEndpoint` is unexported but referenced from `OidcProvider.Endpoint`, so define it under `$defs` as `OidcEndpoint`. ### JSON Schema `type` | Go type | Schema type | |---------|-------------| | `string` | `string` | | `bool` | `boolean` | | `int`, `int64`, `uint32` | `integer` | | `float64` | `number` | | `[]T` | `array`, with `items: { ... }` | | `map[string]T` | `object`, with `additionalProperties: { ... }` | | `*T` (pointer) | same as `T`. If `*int`, allow `null`: `type: [integer, "null"]` | | `*Struct` | `{ $ref: "#/$defs/Struct" }` | ### Constraints from tags - **`default:"X"`** → emit `default: X` (cast to the right type — `default:"10"` on `int` becomes `default: 10`). - **`rule:"^...$"`** → emit `pattern: "^...$"`. **Don't** also add a `format:` — the regex is more authoritative. - **`env:"NAME,sensitive"`** → append `(sensitive).` to the `description`. The schema doesn't have a native "sensitive" flag, so this is documentation-only. - **`env:"NAME"`** without `sensitive` → no change to schema. - URL-looking string fields (web hooks, redirect URLs) → add `format: uri` **unless** a `pattern` is already set from a `rule:` tag. ### `enum` discovery `enum` is not always in tags — sometimes it's in code: 1. Check for a `rule:"^a|b|c$"` regex — convert that to `enum: [a, b, c]` instead of a pattern (more useful in IDE). 2. Check for typed constants near the struct (e.g. `SyslogFormat` has `SyslogDefault = ""` and `SyslogRFC5424 = "rfc5424"` → `enum: ["", rfc5424]`). 3. `TeamInviteType` constants (`TeamInviteEmail`, `TeamInviteUsername`, `TeamInviteBoth`) → enum. ### Reusable types → `$defs` Every named struct that appears as a field type gets a `$defs/<TypeName>` entry. Reference via `$ref: "#/$defs/<TypeName>"`. Top-level `properties` should reference, not inline. Exception: `lumberjack.Logger` is external — define a minimal stub `$defs/LumberjackLogger` with the common fields (`filename`, `maxsize`, `maxage`, `maxbackups`, `localtime`, `compress`). Do not try to fully model it. ### `additionalProperties` Leave it **unset** (defaults to `true`). The schema is informational, not strict — making it strict would break existing configs that have stray keys (legacy fields, typos used as comments, etc.). ## Workflow ### 1. Read all four Go files Use `Read` on each file. Do not skim. Note every exported field on every struct. ### 2. Build a mental map: struct → properties For `ConfigType` (the root), list every exported field with its `json:` name, Go type, and any `default:` / `rule:` / `env:` tags. Then for each referenced struct, do the same. Stop when no new structs appear. ### 3. Diff against existing `config.schema.yaml` Before writing, compare what Go has vs. what the schema has: ```bash # List all json tag names in Go grep -hoE 'json:"[^,"]+' util/*.go | sed 's/json:"//' | sort -u > /tmp/go-keys.txt # List all property keys in the schema yq '.properties | keys | .[]' config.schema.yaml | sort -u > /tmp/schema-keys.txt diff /tmp/go-keys.txt /tmp/schema-keys.txt ``` Identify three categories: - **In Go, missing from schema** → add. - **In schema, missing from Go** → remove (the Go struct is the source of truth). - **In both** → check that type / default / pattern still match. Show the user the diff before applying changes if it's larger than ~5 lines. ### 4. Write `config.schema.yaml` Use the **YAML formatting conventions** already established in the file: - Section comments split top-level `properties` into visual groups: `# === Database ===`, `# === HTTP server ===`, `# === Authentication ===`, etc. - Inline-object syntax `{ type: string, default: foo }` for one-property entries. - Multi-line block form when there are 3+ properties or a `description`. - Quote string values that contain `:`, `/`, `+`, `=`, or start with a digit. Don't quote bare identifiers like `string`, `boolean`, `integer`. - `$ref` values are quoted: `{ $ref: "#/$defs/DbConfig" }`. ### 5. Validate After writing, run two checks: ```bash python3 - <<'PY' import yaml, jsonschema with open("config.schema.yaml") as f: schema = yaml.safe_load(f) jsonschema.Draft202012Validator.check_schema(schema) # meta-validation print("schema is valid") # Confirm an existing config.yaml still passes try: with open("config.yaml") as f: cfg = yaml.safe_load(f) errors = list(jsonschema.Draft202012Validator(schema).iter_errors(cfg)) print(f"config.yaml: {len(errors)} error(s)") for e in errors: print(f" {list(e.path)}: {e.message}") except FileNotFoundError: pass PY ``` Both must pass. If `config.yaml` doesn't exist locally, skip the second check — the meta-validation alone is sufficient. ### 6. Don't touch `config.yaml` The user's `config.yaml` may contain stray legacy keys or comments. Do not "clean it up" as part of this skill — the schema generation is a one-way operation Go → schema. If the user wants a cleaner config, that's a separate task. ## Common pitfalls - **`json:"-"` fields**: easy to accidentally include. Always check the tag, not the field name. - **Pointer vs. value**: `*int` is nullable, plain `int` is not. Reflect that in `type`. - **Typo'd filenames**: `util/OdbcProvider.go` (should be `Oidc`) — preserve it; renaming files is out of scope. - **Tag inheritance illusion**: nested structs don't inherit tags from their parent field. The `default:` on `ConfigType.MaxParallelTasks` is on the field, not on `int`. - **`sensitive` is not standard**: JSON Schema has no built-in sensitive marker. Encode it in `description` text only. - **Existing keys with apostrophes** in `config.yaml` (e.g. `"'email_sender"`) are user-side comment hacks — ignore them, they're not in any Go struct. ## When to refuse If the user asks to add a property to the schema that **doesn't exist in `ConfigType`** ("just add a `foo` field so my config validates"), refuse and explain: the schema is generated from Go. The fix is to add the field to the Go struct first, then regenerate. If `ConfigType` has been heavily refactored and a previous schema entry no longer maps, propose the deletion explicitly before doing it — never silently drop entries that the user might have been relying on.  # License Policy for Semaphore UI This is the source of truth for which open-source licenses are acceptable in Semaphore UI dependencies. The policy is enforced by `scripts/check_policy.py` — if you change anything here, mirror the change in that script. The policy exists for two reasons: 1. **Customer obligations.** Our MSA commits us to *not* shipping components on terms that would require customers to license or assign their IP. That rules out copyleft licenses with strong reciprocity (GPL family, AGPL, SSPL). 2. **Project sustainability.** Source-available-but-not-OSS licenses (BUSL, Commons Clause, Elastic 2.0) carry use restrictions that conflict with our open-source distribution model. ## Allowed (no review needed) These are permissive licenses with attribution-only obligations. Anything under one of these can be added without further discussion. | SPDX ID | Name | |---------|------| | MIT, MIT-0 | MIT License | | Apache-2.0 | Apache License 2.0 | | BSD-2-Clause | BSD 2-Clause "Simplified" | | BSD-3-Clause | BSD 3-Clause "New" | | ISC | ISC License | | Zlib | zlib License | | Unlicense | The Unlicense | | CC0-1.0 | Creative Commons Zero | | MPL-2.0 | Mozilla Public License 2.0 (file-level copyleft, OK for libraries) | | 0BSD | BSD Zero Clause | | BlueOak-1.0.0 | Blue Oak Model License | | Python-2.0 | Python Software Foundation License | **Note on MPL-2.0:** MPL is allowed because its copyleft obligation is at the *file* level, not the project level. We can use MPL-licensed libraries without making Semaphore UI MPL. If we ever modify an MPL-licensed file, that file must remain MPL. ## Review required These licenses are not blanket-forbidden but require a case-by-case decision. Pause and ask before merging a dependency under one of these. | SPDX ID | Why review | |---------|------------| | LGPL-2.1, LGPL-3.0 (and `-or-later`) | LGPL is fine for **dynamic** linking, but Go statically links by default. An LGPL Go library would force us to provide object files so users can relink. Acceptable only if the library is genuinely irreplaceable and we can document the relinking pathway. | | EPL-1.0, EPL-2.0 | Eclipse Public License has weak copyleft and an explicit patent clause. Generally workable but worth a legal eyeball. | | CDDL-1.0, CDDL-1.1 | File-level copyleft like MPL, but with extra requirements. Rare in our ecosystem. | | EUPL-1.1, EUPL-1.2 | European Union Public License. Compatible with several other licenses; check the specific version. | | OFL-1.1 | SIL Open Font License. Almost always fine for embedded fonts, but verify the font is being used as intended (not redistributed standalone with a new name). | ## Forbidden A dependency under one of these licenses **must not be added**. If `check_policy.py` flags one, the options are: (a) remove it, (b) replace it with a permissively-licensed alternative, (c) move the functionality out of process (subprocess invocation breaks the linkage in most cases — this is why Ansible is acceptable). | SPDX ID | Why forbidden | |---------|--------------| | GPL-2.0, GPL-3.0 (and `-only` / `-or-later`) | Strong copyleft. Linking forces Semaphore UI to be GPL, which conflicts with our distribution model. | | AGPL-1.0, AGPL-3.0 | Same as GPL plus a network-interaction trigger. Particularly hostile to SaaS/self-hosted server software. | | SSPL-1.0 | MongoDB's Server Side Public License. Not OSI-approved; imposes obligations on anyone offering the software as a service. | | BUSL-1.1 | Business Source License. Time-delayed open source with use restrictions during the change window. Not OSS. | | Commons-Clause | Restricts commercial sale; strips OSS status from any underlying license it's attached to. | | Elastic-2.0 | Elastic License v2. Use restrictions; not OSS. | | RSALv2 | Redis Source Available License v2. Same family as BUSL/Elastic. | | CC-BY-NC-* | Creative Commons "Non-Commercial" variants. Not usable in a commercially-distributable product. | | Facebook-BSD-Patents (legacy) | The old React patent grant clause. Removed years ago, but flagged here as a defensive measure. | ## Subprocess exception (External Runtime Tools) Tools that Semaphore UI invokes via `os/exec` (Ansible, Terraform, OpenTofu, Pulumi, Bash) are NOT linked into our binary and NOT redistributed by us. Their licenses govern the user's installation of those tools on the host system, not our distribution. This is why we can integrate with Ansible (GPL-3.0) and Terraform (BUSL-1.1) without violating this policy — we never embed their code, we only document that the user must install them separately. These tools are intentionally **not listed** in `THIRD-PARTY-LICENSES.md`. Listing them would wrongly imply that they are distributed with the product and would invite unnecessary scrutiny from a customer's legal team. Neither `collect_licenses.sh` nor `generate_md.py` produces or accepts an external- tools section. ## When the policy itself needs to change If a dependency we genuinely need is forbidden, the path forward is: 1. Document the technical need (what does it do, what alternatives exist). 2. Get sign-off from a maintainer with the authority to make that call. 3. Update **both** this document and `check_policy.py`, in the same commit. 4. Note the exception in `THIRD-PARTY-LICENSES.md` so customers can see it. Don't relax the policy silently. The whole point is that customers can audit us, so the policy must be auditable too.  # THIRD-PARTY-LICENSES.md output format This is the canonical structure that `scripts/generate_md.py` produces. Reference for humans reviewing the generator output, and for anyone who needs to understand what each section is for. ## Structure ``` # Third-Party Licenses [intro paragraph explaining what this file is and why it exists] _Generated on YYYY-MM-DD HH:MM UTC by scripts/collect_licenses.sh._ [regeneration instructions — always include these so the file is reproducible by anyone, not just the original author] ## Summary [total component count] | Ecosystem | Components | |-----------|------------| | Go (backend) | NN | | npm (frontend) | NN | ### License distribution | License | Count | |---------|-------| | MIT | NN | | Apache-2.0 | NN | | BSD-3-Clause | NN | | ... | NN | ## Go Backend Dependencies [one-line description of what these are and where they come from] | Component | Version(s) | License | Source | |-----------|------------|---------|--------| | `github.com/foo/bar` | v1.2.3 | MIT | [link](https://...) | | `github.com/foo/baz` | v0.4.1, v0.5.0 | Apache-2.0 | [link](https://...) | | ... ## Frontend Dependencies (npm) [one-line description] | Component | Version(s) | License | Source | |-----------|------------|---------|--------| | `vue` | 3.4.21 | MIT | [link](https://...) | | `vuetify` | 3.5.8 | MIT | [link](https://...) | | ... --- ## License texts [paragraph explaining where to find full license texts and how to report missing/incorrect attributions]  ``` ## Why this structure **Summary table at the top.** Lets a reader (especially a customer's compliance team) see the shape of the dependency tree at a glance without scrolling through hundreds of rows. **License distribution.** Surfaces concentration risk. If 95% of deps are MIT/Apache and 1 is MPL-2.0, that 1 deserves attention. It also makes it easy to spot a forbidden license that somehow slipped through (a single GPL-3.0 row in the distribution table is a very loud red flag). **Sorted alphabetically within each section.** Diffs between releases become useful — a new dependency shows up as an added row in one predictable place, not scattered across the file. **Versions collapsed onto one line.** A dependency pinned at multiple versions (common with transitive Go deps that get MVS-resolved differently in different parts of the tree) shouldn't take 5 rows. One row, comma- separated versions. **External tools deliberately excluded.** Ansible, Terraform, OpenTofu, Pulumi, and Bash are invoked as subprocesses, not linked, and not redistributed with Semaphore UI. They are not listed in this file — including them would wrongly imply distribution. The license policy document covers them under "Subprocess exception" if a reviewer asks why they're absent. **Regeneration instructions in the header.** Means the file is not a hand-maintained artifact that drifts. Anyone can rebuild it and verify it matches what's actually in the dependency manifests. **Footer comment marker.** `` lets CI verify the file wasn't truncated mid-write — useful when generation runs in a pipeline and might fail partway. ## What NOT to include - **Full license texts inline.** Don't copy the MIT license text 200 times into one file. Refer readers to the source URL. The packages themselves carry their LICENSE files; the user has them on disk after `go mod download` / `npm install`. - **CVE / vulnerability info.** That belongs in security advisories, not the license document. Mixing the two confuses the reader and makes the file go stale faster. - **Internal-only dependencies.** Build tooling (linters, test frameworks, code generators) doesn't ship to customers. Production dependencies only. - **Hand-edited rows.** If something needs a special note, add it via the generator (extend `generate_md.py`), not by editing the output file. Hand edits get destroyed on the next regeneration.  --- name: semaphore-third-party-licenses description: > Generate or update the THIRD-PARTY-LICENSES.md file for the Semaphore UI repository. Use this skill whenever the user asks to create, update, regenerate, audit, or refresh third-party license attributions, OSS notices, SBOM-style license inventories, or NOTICE files for Semaphore UI. Trigger on phrases like "third-party licenses", "OSS notices", "license attribution file", "SBOM for licenses", "NOTICE file", "audit dependencies", "licenses for go.mod / package.json", or any request that mentions compliance with customer agreements requiring an OSS components list. Also trigger when the user says "we added a new dependency, regenerate licenses". This skill knows the Semaphore UI layout (Go backend + Vue.js frontend), the project's license policy (allowlist/denylist), and the canonical output format. --- # Semaphore UI — Third-Party License Generator This skill produces `THIRD-PARTY-LICENSES.md` for the Semaphore UI repository. The file lists every open-source dependency shipped with Semaphore UI by **name**, **version**, **license**, and **source URL**, grouped by component. It exists to satisfy contractual obligations toward customers (identification of OSS components by name, version, and license type) and to preserve attribution required by permissive licenses (MIT/BSD/Apache-2.0). ## Repository layout you can expect Semaphore UI is a self-hosted product. The repository ships: - **Go backend** — module file at `go.mod`, source under `pkg/`, `services/`, `db/`, etc. - **Vue.js frontend** — `web/package.json` (or `web2/package.json` in some branches), built into static assets and embedded in the Go binary. External CLI tools (Ansible, Terraform, OpenTofu, Pulumi, Bash) are invoked at runtime as separate operating-system processes. They are NOT linked into the binary and NOT redistributed with Semaphore UI, so they are intentionally **not listed** in `THIRD-PARTY-LICENSES.md` — their license terms apply to the user who installs them on the host, not to Semaphore UI's distribution. The license policy still discusses why this is contractually safe (see `references/license_policy.md`, "Subprocess exception"). If the layout differs (monorepo restructure, new submodule, etc.), inspect the repo first with `find . -name "go.mod" -o -name "package.json" -not -path "*/node_modules/*"` and adapt. ## Workflow Follow these steps in order. Don't skip the policy check — it's the part that actually protects the project from accidentally shipping a GPL'd dependency. ### 1. Confirm scope with the user Before generating anything, ask (briefly) which targets to include if it's not obvious from context: - Backend only? Frontend only? Both? - Production dependencies only, or also dev dependencies? **Default**: both backend and frontend, **production-only** (dev dependencies are not distributed to customers and don't need attribution). Override only if the user explicitly asks for dev deps too. ### 2. Collect raw license data Run `scripts/collect_licenses.sh` from the repo root. It does the following: - Sets `GOWORK=off` and runs `go-licenses report ./... --template scripts/go_template.tpl` for the Go backend, so workspace siblings (e.g. `pro_impl`) are not pulled in. - Rolls sub-package rows up to their parent module (uses `go list -m all` for the module → version map) and drops any module path that belongs to the root module's namespace (first-party packages, including `replace … => ./pro` targets). - Applies a small `OVERRIDES` table in the script for modules where `go-licenses` can't auto-detect a license (e.g. `modernc.org/mathutil` → BSD-3-Clause). Extend the table when new "Unknown" entries appear. - Runs `license-checker --production --json --excludePrivatePackages` in the frontend directory and strips the low-confidence `*` suffix from license strings so `MIT*` collapses into `MIT`. - Writes raw output to `.licenses-cache/go.tsv` and `.licenses-cache/npm.json`. If the tools aren't installed, the script prints the install commands. Don't try to install them silently — show the user what needs to be added so they can decide whether to add them to CI. ### 3. Run the policy check Run `scripts/check_policy.py .licenses-cache/`. This compares every detected license against the project policy in `references/license_policy.md`: - **Allowed** (green): MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, Zlib, Unlicense, CC0-1.0, MPL-2.0 — proceed. - **Review** (yellow): LGPL-2.1, LGPL-3.0, EPL-2.0, CDDL-1.0, custom/unknown — pause and ask the user. LGPL is fine for dynamic linking but Go statically links, so flag it for review. - **Forbidden** (red): GPL-2.0, GPL-3.0, AGPL-3.0, SSPL-1.0, BUSL-1.1, Commons Clause, "non-commercial" clauses — STOP. Do not proceed with file generation. Report the offending package and ask the user how to handle it (replace, vendor, or accept and document the consequence). **This step is non-negotiable.** A forbidden license slipping into THIRD-PARTY-LICENSES.md isn't just a documentation problem — it's a contract breach with every customer. If `check_policy.py` returns a non-zero exit code, surface the failures prominently and stop. ### 4. Generate the markdown Run `scripts/generate_md.py .licenses-cache/ > THIRD-PARTY-LICENSES.md`. This produces the file using the structure described in `references/template.md`. Key points the generator handles: - Sorts entries alphabetically within each section. - Groups by component category (Go backend / npm frontend). - Deduplicates packages that appear at multiple versions (lists all versions on one line). - Renders a summary table at the top with license counts. - Adds a generation timestamp and a note pointing to `scripts/collect_licenses.sh` so the file is reproducible. ### 5. Verify and commit After generation: 1. Diff against the previous `THIRD-PARTY-LICENSES.md` (if it exists). New rows = new dependencies — confirm with the user that they're expected. 2. Verify the file isn't truncated and ends with the closing footer (``). 3. Suggest the commit message: `chore(licenses): regenerate THIRD-PARTY-LICENSES.md for vX.Y.Z`. 4. If a CI pipeline exists (`.github/workflows/`), suggest adding a job that runs `scripts/check_policy.py` on every PR — that's how the project prevents regressions, not by re-checking manually each release. ## Notes on edge cases **Vendored dependencies.** If the repo has a `vendor/` directory, `go-licenses` will read from it. That's fine — vendored code still ships and still needs attribution. **Dual-licensed packages.** Some packages are offered under "MIT OR Apache-2.0". Pick MIT (the simpler one) and note the choice in the entry: `License: MIT (also available under Apache-2.0)`. **Packages with no detectable license.** `go-licenses` flags these as "Unknown". Don't ship the file with Unknowns — manually inspect the repo, fill in the SPDX identifier, and if there's truly no license, treat the package as forbidden (no license = "all rights reserved", which is incompatible with redistribution). **Ansible / Terraform / OpenTofu / Pulumi / Bash.** Do NOT list them in `THIRD-PARTY-LICENSES.md`. They are invoked as separate OS processes (`os/exec`), not linked, not redistributed. Their licenses bind the user who installs them on the host, not Semaphore UI's distribution. Listing them would imply otherwise and is an unnecessary signal to a reviewing customer's legal team. The "Subprocess exception" section in `references/license_policy.md` explains the reasoning if a reviewer asks. **First-party packages with no LICENSE.** The root module and any `replace … => ./<dir>` target (e.g. `./pro`) live inside this repo and don't need to be self-attributed. The collection script filters them out by the root module prefix from `go.mod`. If you see "Unknown license" rows for `github.com/<this-org>/<this-repo>/…`, the filter is working correctly — those rows shouldn't appear in the final cache. **Embedded license texts.** For packages under MIT/BSD/ISC, the license requires preserving the copyright notice. The generator embeds the full LICENSE file text from each package's source. For Apache-2.0 packages, it embeds the NOTICE file if one exists. ## What this skill does NOT do - It does not generate a CycloneDX or SPDX SBOM. If the user wants a machine-readable SBOM (for compliance scanners, customer attestations, etc.), point them at `syft packages dir:. -o cyclonedx-json` as a separate step. THIRD-PARTY-LICENSES.md is the human-readable artifact. - It does not check for CVEs. That's a security concern, not a licensing one — use `govulncheck` and `npm audit` for that. - It does not modify go.mod or package.json. The skill is read-only with respect to the dependency manifests; it only generates the attribution document. See `references/license_policy.md` for the full policy and `references/template.md` for the output format.  # db-query Ad-hoc SQL runners for the project's local databases — **one script per database**. Each runs the query as that database's app user, read-only by default, and logs every query it runs. | Script | Engine | Mode | Database | `.env` file | `.env` keys | Access | | --- | --- | --- | --- | --- | --- | --- | | `query_<db>.sh` | PostgreSQL / MariaDB | docker / host | `<database>` | `<path>` | `DB_*` | read-only | ## Setup None. Each script reads its connection from the project's own `.env`; the path to it is `ENV_FILE` in the script's settings block. Credentials are never copied into this folder. ## Usage ~~~shell AGENTS/tools/db-query/query_<db>.sh "SELECT id, email FROM users LIMIT 5" AGENTS/tools/db-query/query_<db>.sh -f report.sql echo "SELECT 1" | AGENTS/tools/db-query/query_<db>.sh AGENTS/tools/db-query/query_<db>.sh "SELECT ..." -t -A # trailing flags go to psql / mariadb ~~~ ## Log Every query is appended to `AGENTS/tools/db-query/log/queries.log` before it runs — timestamp, script, target, database, user, access mode, the SQL — and its exit code after. Result rows are not logged. The folder is gitignored. ## Traps - ⚠️ Local only: a remote docker daemon or a non-loopback host is refused. `ALLOW_REMOTE=1` in a script is set only on the user's explicit request — record who asked and when here. - ⚠️ Read-only by default: the session refuses any write (`READ_ONLY=1`). It guards against accidents, not against intent — SQL can switch it off. `READ_ONLY=0` in a script is set only on the user's explicit request — record who asked and when here.  # docs — portable standard by zone Approaches and conventions that would serve another project, not this project's own facts. One folder per zone, each with its own `INDEX.md`. This file routes to a zone; the zone's index routes to the doc. ## Zone index (example) The rows below are example data, illustrating the shape a real routing table takes; replace them once an actual zone exists. | When you need it | Read | | --- | --- | | Example: Writing backend code: models, routes, permissions, entity codes | `backend/INDEX.md` | | Example: Running or writing backend tests — mandatory before the first command | `backend/INDEX.md` | | Example: Editing the frontend: app layout, import boundaries, i18n | `frontend/INDEX.md` | | Example: Setting up a local stack: reverse proxy, HMR behind a proxy, tunnels — the approach, not this project's ports | `infra/INDEX.md` | | Example: Editing an env file or another human-read file: grouping, order, language, line length | `standards/INDEX.md` |  # wf-stand — run and verify workflows on the local stand Drives the agent's throwaway Semaphore stand (`http://localhost:3100`, admin/admin123, project 1, Pro build from HEAD) to execute a workflow end to end and follow every node to a terminal status. Exists because a workflow run is asynchronous: tasks, approvals and delays resolve over time and only the run-details endpoint shows all of them together. Call forms (from the repository root): ``` AGENTS/tools/wf-stand/stand.sh {start|stop|restart|build|status|log [n]} AGENTS/tools/wf-stand/seed.sh AGENTS/tools/wf-stand/seed-outputs.sh # PROJECT_NAME="…" to seed another project AGENTS/tools/wf-stand/run.sh <workflow_id> [--approve|--reject] [--stop-after SEC] [--expect success|failed|stopped] [--timeout SEC] [--run ID] AGENTS/tools/wf-stand/runner.sh {start|stop|status|tag|untag} # PID=<project> TAG=<tag>; remote runner for the stand AGENTS/tools/wf-stand/inputs.sh <workflow_id> [run_id] # outputs stored per producer + "INPUT name=value" lines per consumer NODE_PATH=~/.npm/_npx/9833c18b2d85bc59/node_modules node AGENTS/tools/wf-stand/shoot-run.cjs <workflow_id> [run_id] [out.png] [--dark] AGENTS/tools/wf-stand/seed-docs.sh # project "Demo Stand" + workflow "Build and deploy" for the docs screenshots AGENTS/tools/wf-stand/seed-survey.sh # workflow "Survey: workflow variables" (survey + node bindings) in the seed-outputs project NODE_PATH=… node AGENTS/tools/wf-stand/shoot-editor.cjs <workflow_id> [node_title] [out.png] [--dark] # editor with a node selected: survey panel, canvas, bindings NODE_PATH=… node AGENTS/tools/wf-stand/shoot-run-dialog.cjs <workflow_id> [out_dir] [--dark] # starts a run through the survey dialog; shoots the dialog and the run view's Variables strip PID=<project> WF=<workflow> NODE_PATH=… node AGENTS/tools/wf-stand/shoot-docs.cjs # the four screenshots of workflows.md § Outputs and inputs ``` Examples: ``` $ AGENTS/tools/wf-stand/stand.sh build && AGENTS/tools/wf-stand/stand.sh start stand: up at http://localhost:3100 (pid 40366) $ AGENTS/tools/wf-stand/seed.sh workflows happy=5 branches=6 # ids also in /tmp/semaphore-stand/wf-exec-ids.txt $ AGENTS/tools/wf-stand/run.sh 5 --approve --expect success run 4 started (workflow 5) — UI: http://localhost:3100/project/1/workflows/5/runs/4 17:30:14 approval version=0.1.0 n18/task=task#6:success n19/approval=approval:pending n20/delay=- n21/task=- 17:30:14 node 19 -> approved 17:30:24 success version=0.1.0 n18/task=task#6:success n19/approval=approval:approved n20/delay=delay:success n21/task=task#7:success final: success (run 4) $ AGENTS/tools/wf-stand/run.sh 6 --stop-after 8 --expect stopped final: stopped (run 6) ``` Seeded workflows: "Exec happy" (task → approval → delay 5 s → task, ends `success` with `--approve`) and "Exec branches" (ok → fail; on_failure → recover, on_success → never started; always → 30 s slow task; ends `failed`). Templates are `bash` scripts from the local repo `/tmp/semaphore-stand/wf-repo` (`ok.sh`, `fail.sh`, `slow.sh`), so no network or Ansible is needed. `seed-outputs.sh` seeds the project "Artifacts QA" (project 1 since the 2026-10-07 rebuild) for testing workflow outputs by hand: 16 templates (bash producers for every rule of the contract — valid, empty, bad JSON, bad name, 101 outputs, 40 KB value, outputs-then-exit-1, symlink; bash and Ansible consumers with one survey var of every type; Terraform / Tofu with a `sensitive` and a hyphenated output; Ansible `set_stats`) and four workflows: 1 "producers -> consumers" (expect `success`, see `task.artifacts` of tasks of nodes 2–4), 2 "invalid producers" (expect `failed`, each bad producer `error` with the reason in its log, "empty" `success` without artifacts), 3 "failed producer" (expect `failed`, no artifacts stored, `on_failure` consumer ran), 4 "tofu -> consume" (expect `success`). Scripts: `/tmp/semaphore-stand/wf-repo/produce*.sh`, `consume.sh`, `tf/main.tf`, `playbooks/*.yml`. Ids land in `/tmp/semaphore-stand/wf-outputs-ids.txt`. Since 2026-10-08 the same seed adds the mapping checks: templates "bash: produce renamed outputs" and "ansible: set_stats renamed outputs" (output names `tag`, `count`, `flag`, `subnets`, `cfg`, `envname` that match no survey variable, so only an explicit edge mapping can deliver them) and workflows 9 "Inputs: explicit mapping" (renamed producers → bash and ansible consumers over `explicit` edges, `image_tag←tag`, `replicas←count`, …), 10 "Inputs: by_name through approval" (produce → approval → consumers, run with `--approve`), 11 "Inputs: fan-in by_name vs explicit" (produce by name and renamed explicitly into one consumer with convergence all: expect `image_tag` from the explicit edge, `replicas` by name), 12 "Inputs: explicit empty list" (the edge passes nothing). Consumers print one `INPUT name=value` line per survey variable (bash: parsed `k=v` args plus `env:env_name` — a `target: env` variable keeps its own name, it is not upper-cased; ansible: a debug list), so `inputs.sh <wf>` shows producer outputs next to what the consumer received. Expected since the resolver landed (2026-10-08): workflow 1 and 10 — the consumer's `INPUT` lines repeat the producer's `image_tag`, `replicas`, `enabled`, `subnet_ids`, `config` (by name; `env-name` with a hyphen is not delivered); workflow 9 — the renamed values (`image_tag=renamed-…`, `replicas=7`, `env:env_name=prod`); workflow 11 — `image_tag=renamed-…` from the explicit edge and `replicas=3` by name; workflow 12 — only `image_tag=static-from-node`, `replicas=1` (the default) and `env:env_name=static-env`; workflow 3 — the on_failure consumer is `error` before start with "Required input(s) without a value: image_tag" in its log. The task log of every consumer starts with the engine's `Input "<var>" <- output "<key>" of node N (task #M)` lines, so a value's source is always one line above the value. Since 2026-10-09 the seed also covers the Jinja rule (Ansible never evaluates an expression inside an extra var — every value reaches it through a file, the ones with a Jinja2 delimiter tagged `!unsafe`): template "bash: produce jinja outputs" (`produce_jinja.sh` writes `image_tag`, `config` and `replicas` holding `{{ lookup('pipe', …) }}`, `{{ lookup('env', 'HOME') }}`, `{{ 6*7 }}`), the variable group "vars group with jinja" (`group_expr: "{{ 2*21 }}"`), template "ansible: consume + vars group" and workflows 13 "Inputs: jinja injection" (→ ansible and bash consumers) and 14 "Inputs: jinja vs vars group". Expected on the server and on the runner: `INPUT image_tag={{ lookup('pipe', 'echo INJECTED-$(id -un)') }}`, `config` with the expressions verbatim, `replicas=1` (the default — `{{ 6*7 }}` is not an int) and `INPUT group_expr={{ 2*21 }}` — the variable group is data too. A consumer log containing `INJECTED-` or `group_expr=42` means Ansible evaluated a value: a regression. `inputs.sh` right after `run.sh` on the runner can miss the last log lines; re-run it with the run id. Trap: the template API ignores `environment_id`, pass `environment_ids`. Since 2026-10-10 the stand also checks the secret extra vars (TASK@CEA87DDD08): the survey secret `token` and the variable-group secret `db_password` (type `var`, added to "vars group with jinja" by hand through `PUT /project/1/environment/1` with `secrets:[{type:"var",name,secret,operation:"create"}]`) reach Ansible through a second, vault-encrypted `--extra-vars @task_<id>_secret_vars_*.yml` with a one-off `--vault-id <guid>@prompt`. `playbooks/consume.yml` prints `INPUT token=…` and `INPUT db_password=…`; template 37 "ansible: consume + own vault" (access key "tpl vault", type login_password, vault `default`) runs `playbooks/consume_vault.yml`, which loads `playbooks/vaulted.yml` (encrypted by `ansible-vault` with that key's password) through `vars_files` and prints `INPUT vaulted_var=…`. Expected on the server and on the runner: `INPUT token=s3cr3t {{ 1+1 }}`, `INPUT db_password=p@ss {{ 7*6 }}` literally; `ps -axo args=` shows `--vault-id=<guid>@prompt` and two `--extra-vars @`, never a secret or the password; `grep -rl s3cr3t /tmp/semaphore-stand/tmp` (or `runner-tmp`) finds nothing while the task runs; no `task_*_vars_*` file is left after. With `SEMAPHORE_LOG_LEVEL=DEBUG SEMAPHORE_DEBUG_FILTER=extra_vars` exported before `stand.sh start` / `runner.sh start`, the server and runner logs show seven `context=extra_vars` lines per task (split, two files written, vault added, two files removed, password forgotten). Checked 2026-10-10: server task 162, runner task 164, own vault task 171, regression runs 39 (wf 13) and 40 (wf 14). Traps: a vault-encrypted file must not sit in `playbooks/group_vars/` — Ansible loads it for every playbook of the directory and a template without that vault fails with "Decryption failed"; `vars_files` of the repository are still templated (`{{ 3*3 }}` prints `9`) — only values Semaphore passes are `!unsafe`; `runner.sh start | tail` hangs because the runner inherits the pipe — redirect to a file instead; a PUT of a template without the `vaults` field deletes its vaults, which is why `runner.sh tag/untag` re-reads each template by id before the PUT. Docs screenshots (2026-10-11): `seed-docs.sh` seeds a separate project "Demo Stand" (the name the published editor screenshot already shows) with "Provision network" (bash, outputs `vpc_id`, `subnet_ids`), "Build image" (bash, outputs `image_tag`, `replicas` — the values quoted in the user guide), "Deploy to cluster" (ansible `playbooks/deploy.yml`, survey `image_tag`, `replicas`, `subnets`) and the workflow "Build and deploy": Provision → Build → Deploy by name plus Provision → Deploy explicit (`subnets ← subnet_ids`). Run it once (`PID=<p> run.sh <wf> --expect success`), then `shoot-docs.cjs` writes `workflow-inputs-explicit.png`, `workflow-inputs-by-name.png`, `workflow-run-outputs.png` and `task-outputs.png` (dialog clipped) to `/tmp/semaphore-stand/shots-docs`; convert with `cwebp -q 88` into `docs/static/assets/`. Traps: a workflow must have exactly one root node (the explicit edge alone would make Provision and Build two roots); key hints need a run of the current revision, so re-run after any re-seed; the editor fits a three-node graph at ~45 % on a 1440 px viewport — the script collapses the palette (`.WorkflowEditor__sideToggle`) and clicks the fit control after the side panel opens instead of zooming in, which pushes nodes under the panel. Seeding traps learned there: a Terraform-family template must be POSTed without `inventory_id` (the API creates a `terraform-workspace` inventory; a shared one gets claimed and hidden) and with `task_params.auto_approve`, or a plan with changes parks the task in `waiting_confirmation`; a workflow must have exactly one root node; `survey_vars[].default_value` is a plain string; a JSON `\"` inside `$( )` inside a double-quoted bash string is mangled — build such fragments in a variable first. Traps: `run.sh` exits 1 when `--expect` does not match or `--timeout` (default 180 s) passes; `--approve` resolves every pending approval it sees, so use `--run ID` to only follow an existing run. `stand.sh build` rebuilds the Vue app into `api/public` (a tracked-ignored embed input) and the binary at `/tmp/semaphore-stand-bin`; it needs the `pro_impl` workspace for Workflows to be enabled. The stand DB is `/tmp/semaphore-stand/database-wf.sqlite` and persists between sessions. `runner.sh` registers a global runner "wf-runner" (tag `wf`, local executor, `/tmp/semaphore-stand/runner-config.json`, log `runner.log`) and starts it from the same binary; `tag` sets `runner_tag` on every template of project `PID` (default 1) so their tasks go to it, `untag` sends them back to the server. The remote-runner check of workflow outputs (2026-10-08): `runner.sh start && runner.sh tag && run.sh 1 --expect success && run.sh 2 --expect failed`, then `sqlite3 /tmp/semaphore-stand/database-wf.sqlite "select id,status,runner_id,length(artifacts) from task order by id desc limit 13"` shows `runner_id` of the runner and `artifacts` on the producers only. Traps: the token is returned once at creation, so a runner whose config file is gone is deleted and recreated; stop the runner and `untag` before a session that expects tasks to run on the server, or they wait forever; `status` keeps saying `online` for up to 120 s after `stop` (the server's heartbeat timeout), trust the `process:` line. `seed-survey.sh` (2026-10-16, TASK@B197C72B7F) needs the templates of `seed-outputs.sh` and adds workflow "Survey: workflow variables": survey `env` (enum, default `staging`), `image_tag` (required), `replicas` (int, default 2); node 2 "bash: consume" bound `image_tag←image_tag`, `replicas←replicas`, `env_name←env` on top of static `image_tag=static-from-node`; node 3 the same template without bindings (must receive nothing although the names match); node 4 "bash: produce renamed outputs" → node 5 "bash: consume" over an explicit edge `replicas←count` plus the binding `image_tag←image_tag`. Start a run with a body: `POST …/workflows/<id>/runs {"environment":{"image_tag":"1.2.3","env":"prod"}}` (ids in `/tmp/semaphore-stand/wf-survey-ids.txt`). `shoot-editor.cjs` logs in, opens the editor, clicks the first card whose title matches, scrolls the first bound survey field into view and writes the page, a crop of the task params card (`<out>-fields.png`) and the open assign menu (`<out>-assign.png`). `shoot-run-dialog.cjs` opens the workflow page, presses Run, checks that an empty required answer is refused, fills `image_tag` (`IMAGE_TAG`, default 1.2.3) and the first enum option, starts the run and shoots `run-dialog-invalid.png`, `run-dialog.png` and `run-view-variables.png` in `out_dir`; it prints the run id and the Variables chips. ⚠️ 2026-10-16: macOS purges files (not directories) under `/tmp` that were not touched for ~3 days — `config-wf.json`, `database-wf.sqlite`, the admin user and every script in `wf-repo` vanished between sessions. `stand.sh build` + a fresh `config-wf.json` (sqlite at `$DIR/database-wf.sqlite`, port `:3100`, three `openssl rand -base64 32` keys, `use_remote_runner: true`), `migrate`, `user add --admin --login admin --password admin123` and the seeds bring it back; `wf-repo` scripts must be recreated before any run.  # mocks — approved mock, screenshots and the scripts that shoot them Design artefacts of the editor redesign (`TASK@88179c9bc1`); decisions are in `../editor-architecture.md`, not here. Every script targets the local stand `http://localhost:3100` (admin/admin123, project 1) and Playwright loaded through `NODE_PATH` with `channel: 'chrome'` — stand and Playwright recipes are in `AGENTS/memory/ui-stands.md`. ## Files | File | What it is | | --- | --- | | `2026-09-26-workflow-node-mock.html` | Approved static mock: editor canvas, run view, card states, empty state; `#dark` in the URL flips the theme. Open from the repo checkout — MDI icons load from `web/node_modules`. Its "Tab opens quick-add" hint is stale (see ⚠️ in `editor-architecture.md`). | | `2026-09-26-workflow-node-mock-{light,dark}.png` | Renders of the mock as approved. | | `workflow-editor/editor-{light,dark}.png`, `editor-selected-*.png`, `editor-quickadd-light.png`, `editor-legacy-*.png`, `editor-empty-light.png`, `run-{light,dark}.png` | Screenshots of the shipped UI at 1440 × 900 @2x, shot by `shoot-wf.cjs`. "Legacy" is a workflow saved without positions (auto layout). | | `workflow-editor/editor-interactions.png` | End state of the `interact-wf.cjs` checklist. | | `workflow-editor/run-approval-pending.png`, `run-delay-countdown.png` | Run view with a pending approval and the delay countdown, from `approve-wf.cjs`. | | `workflow-editor/editor-edge-explicit-{light,dark}.png`, `editor-edge-byname-{light,dark}.png`, `run-outputs-{light,dark}.png`, `task-outputs-{light,dark}.png` | Workflow inputs (2026-10-09, `TASK@1845d9d4d7` stage 7): the edge panel with "Map inputs explicitly" and the mapping table (keys suggested from the last run), the by_name panel with the destination's survey variables (a check on those the source produced), the run view with "N outputs" on producer cards and the swap icon on explicit pills, the task dialog's Outputs panel. Shot by `shoot-inputs.cjs` on the "Artifacts QA" project. | | `survey/editor-bindings.png`, `survey/editor-bindings-fields.png`, `survey/editor-bindings-assign.png`, `survey/editor-problem.png` | Workflow survey variables (2026-10-16, `TASK@B197C72B7F` stage 7, redesigned the same day on the owner's request): the editor with the survey in the left panel, "3 from workflow" on a bound card and the node panel whose bound survey fields are read-only with a link icon and an unbind cross; a crop of the task params card; the "assign a workflow variable" menu open next to an unbound field; the same workflow after the variable "Image tag" was deleted — "2 problems", Save disabled, badges on the bound nodes and the error under the orphaned field. Shot by `AGENTS/tools/wf-stand/shoot-editor.cjs` on workflow 11 of "Artifacts QA" (`seed-survey.sh`). | | `survey/run-dialog.png`, `survey/run-dialog-invalid.png`, `survey/run-view-variables.png` | Workflow survey at run time (2026-10-16, `TASK@B197C72B7F` stage 8): the "Run" dialog with the survey fields seeded from the defaults, the same dialog refusing an empty required answer, and the run view with the "Variables" strip (`run.environment`) under the toolbar. Shot by `AGENTS/tools/wf-stand/shoot-run-dialog.cjs` on workflow 11 of "Artifacts QA". | | `workflow-editor/editor-revision-active-run.png`, `run-after-edit.png` | Revisions (2026-09-27): the editor with the "rev. 3" and "1 active run" chips, and run #8 still rendered on its revision 1 after two later saves. Shot with `AGENTS/tools/wf-stand/shoot-run.cjs`. | ## Scripts | Script | Does | Needs | | --- | --- | --- | | `seed-wf.sh` | Seeds five templates (one with an XSS name), the "Release" workflow with positions, the position-less "Nightly checks" (with a `<script>` note), starts one Release run; writes ids to `/tmp/semaphore-stand/wf-ids.txt`. Idempotent for templates. | Running stand, repository 1 and inventory 1 in project 1. | | `shoot-wf.cjs` | Editor/run/legacy/empty screenshots in light and dark; output `OUT` (default `/tmp/semaphore-stand/shots-wf`), `RUN` selects the run id. | `wf-ids.txt`. | | `interact-wf.cjs` | 16 PASS/FAIL checks on the editor: quick-add from the port, palette click, drag connect, cycle guard, pill condition change, snap, Delete, undo/redo round trip, problem badge + disabled Save, leave guard. Exits 1 on any FAIL or page error. | `wf-ids.txt`. Mutates the Release workflow in the browser but does not save. | | `approve-wf.cjs` | Approve inside the card, delay countdown ticks, viewport survives polling, task log opens on click. | `/tmp/semaphore-stand/wf3.txt` with `<workflow id> <run id>` of a run waiting at an approval — seeded by hand, not by `seed-wf.sh`. | | `keys-wf.cjs` | Keyboard pan/zoom/fit/reset in the editor and the run view; asserts no effect while typing in the properties panel. | `wf-ids.txt`, run 2 of Release. | | `shoot-inputs.cjs` | Shoots the four inputs screenshots above and runs 7 PASS/FAIL checks (checkbox state, mapping rows, hint line, by_name chips with a matched output, output count on a card, Outputs panel in the task dialog). `--dark` for the dark theme; `WF` (default 9, explicit workflow), `WF_BYNAME` (default 1), `OUT` (default `/tmp/semaphore-stand/shots-inputs`). Edges are selected by a dispatched `mousedown` on the path — a real click lands on the condition pill. | `AGENTS/tools/wf-stand/seed-outputs.sh` seeded, a finished run of the current revision of both workflows (`run.sh 9`, `run.sh 1`) for the key hints. | | `interact-inputs.cjs` | 10 PASS/FAIL checks of the inputs round trip on workflow `WF` (default 12): select the explicit edge, not dirty before editing, type a key, dirty, explicit icon on the pill, Save → API shows the pair, uncheck → by_name chips, Save → fields gone, original graph restored by PUT. Exits 1 on any FAIL or page error. | Running stand with the seeded project; mutates workflow 12 and restores it. | | `shoot-nodes.cjs` | Crops one card per node kind (task hovered with the "+", approval, delay, note) with edge pills hidden and zoom 1; source of `docs/static/assets/workflow-node-*.webp`. | `WF` env = id of the "Docs node kinds" workflow on the stand (default 4). | | `make-hotkeys-svg.py <out.svg>` | Generates the keyboard cheat-sheet `docs/static/assets/workflow-hotkeys.svg`; edit `COLUMNS` and re-run when a shortcut changes. | Python 3 only.

Read and follow .claude/CLAUDE.md before starting any work. # Claude Code Instructions # Documentation The documentation stored in /docs directory. It is a submodule with official Semaphore UI documentation in on Docusaurus engine. You should actualize the documentation for new and updated featues. ### Generated reference pages `docs/docs/reference/configuration.md` and `docs/docs/reference/cli/commands.md` are generated from this repository and must never be edited by hand: - `tools/docsref` reads the struct tags and doc comments of `util.ConfigType`. - `tools/clidocs` walks the real Cobra command tree from `cli/cmd`. After changing a configuration option or a CLI command, run `task docs:gen` and commit the result together with the code. The `docs-reference` job in `.github/workflows/dev.yml` fails when the committed pages differ from what the generators produce. A config field with no doc comment falls back to `tools/docsref/descriptions.json`. Prefer writing the doc comment: `docsref` prints how many options still depend on that file, and the number should only fall. ## Writing Plans All plans, tasks, researches for AI agents stored in folder AGENTS. Each plan has markdown-format and stored in folder AGENTS/plans/. Plan can be split to tasks. Each task describes in details how to implement some part of some plan. ## Code Style 1. Do not use global variables. Global variables are forbidden. ## High Availability Support All solutions must work in High Availability mode. ## Security Is the #1 Priority All solutions must be secure by design. Do not consider any solution that introduces security risks. ## How to do research Use MCP server `research` if your asks you to research something. ## Writing Tests Use `github.com/stretchr/testify/assert` (and `require` when a failure should stop the test immediately). ### Run tests ```bash go test ./path/to/package/ -run TestFunctionName -v -count=1 ``` ### Rules - Test file goes next to the source: `foo.go` → `foo_test.go`, same package. - Use `assert.Equal`, `assert.Empty`, `assert.Nil`, `assert.True`, `assert.Panics`, etc. Never use raw `if`/`t.Fatalf` for assertions. - Use `require` (instead of `assert`) when subsequent lines depend on the check passing (e.g., `require.NoError` before using a result). - Use table-driven tests with `t.Run` for multiple inputs to the same function. - Use `t.TempDir()` for temporary files — cleanup is automatic. - When testing code that uses package-level globals (e.g., `util.Config`), initialize them in a helper and reset state between tests. - When testing code that reads `os.Stdin`, swap it with `os.Pipe()` and restore in `defer`. ### Template ```go package mypkg import ( "testing" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) func TestMyFunction(t *testing.T) { // setup input := "value" // act result, err := MyFunction(input) // assert require.NoError(t, err) assert.Equal(t, "expected", result) } func TestMyFunction_TableDriven(t *testing.T) { tests := []struct { name string input string expected string }{ {"short input", "abc", "ABC"}, {"empty input", "", ""}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { assert.Equal(t, tt.expected, MyFunction(tt.input)) }) } } func TestMyFunction_Panics(t *testing.T) { assert.Panics(t, func() { MyFunction(nil) }) } ``` ### Common assertions | Assertion | Use when | |-----------|----------| | `assert.Equal(t, expected, actual)` | Comparing values | | `assert.NotEqual(t, a, b)` | Values must differ | | `assert.Nil(t, val)` / `assert.NotNil(t, val)` | Pointer/interface checks | | `assert.Empty(t, val)` | String, slice, or map is zero-length | | `assert.Contains(t, str, substr)` | Substring or element in collection | | `assert.True(t, cond)` / `assert.False(t, cond)` | Boolean conditions | | `assert.NoError(t, err)` / `assert.Error(t, err)` | Error checks | | `assert.ErrorContains(t, err, "msg")` | Error with specific message | | `assert.Panics(t, func(){...})` | Code must panic | | `require.NoError(t, err)` | Stop test immediately on error | ### Initializing `util.Config` in tests Many packages depend on `util.Config` which is a `*ConfigType` pointer (nil by default). Initialize before use: ```go func setupConfig() { if util.Config == nil { util.Config = &util.ConfigType{} } // Initialize nested pointers as needed: if util.Config.Runner == nil { util.Config.Runner = &util.RunnerConfig{} } } ``` ### HTTP handler tests Use `net/http/httptest`: ```go func TestMyHandler(t *testing.T) { req := httptest.NewRequest(http.MethodGet, "/api/endpoint", nil) w := httptest.NewRecorder() myHandler(w, req) assert.Equal(t, http.StatusOK, w.Code) assert.Contains(t, w.Body.String(), "expected") } ``` AGENTS/agent-primary.md # Semaphore UI Development Instructions **Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.** Semaphore UI is a modern web interface for managing popular DevOps tools like Ansible, Terraform, PowerShell, and Bash scripts. It's built with Go (backend) and Vue.js (frontend), using Task runner for build automation. ## Working Effectively ### Bootstrap, build, and test the repository: - Install Go 1.21+ (currently requires go version 1.21 or higher) - Install Node.js 16+ - Install Task runner: `go install github.com/go-task/task/v3/cmd/task@latest` - Install dependencies: `task deps` -- takes 3 minutes first time (faster with cache). NEVER CANCEL. Set timeout to 5+ minutes. - Build the application: `task build` -- takes 1.5 minutes. NEVER CANCEL. Set timeout to 3+ minutes. - Run tests: `task test` -- takes 33 seconds. NEVER CANCEL. Set timeout to 2+ minutes. ### Run the application: - ALWAYS run the bootstrapping steps first - Setup database and admin user: `./bin/semaphore setup` (interactive, use SQLite option 4 for development) - Start server: `./bin/semaphore server --config ./config.json` - Web UI: http://localhost:3000 (login: admin / changeme) - API: http://localhost:3000/api/ (test with: `curl http://localhost:3000/api/ping`) ## Validation - **CRITICAL**: Always manually validate any new code by building and running the application. - ALWAYS run through at least one complete end-to-end scenario after making changes: 1. Build the application: `task build` 2. Start the server: `./bin/semaphore server --config ./config.json` 3. Test API endpoint: `curl http://localhost:3000/api/ping` (should return "pong") 4. Access web UI at http://localhost:3000 and verify it loads 5. For auth changes: Test login with admin/changeme - For significant changes, run full setup process to ensure setup still works - Always build and exercise your changes before considering the task complete ### Complete Validation Scenario (for major changes): ```bash # 1. Clean build task build # 2. Setup database (if config.json doesn't exist) ./bin/semaphore setup # Choose option 4 (SQLite), use admin/changeme # 3. Start server ./bin/semaphore server --config ./config.json # 4. Test in another terminal curl http://localhost:3000/api/ping # Should return "pong" curl -I http://localhost:3000/ # Should return HTTP 200 # 5. Test web interface manually in browser at http://localhost:3000 # 6. Test login with admin/changeme if auth-related changes ``` ### Linting and Code Quality - Frontend linting: `cd web && npm run lint` (has known warnings about console statements and asset sizes - ignore existing issues) - Backend linting: `golangci-lint run --timeout=3m` (has known type errors due to module import issues - ignore existing issues) - **DO NOT** try to fix existing linting issues unless specifically asked to - Always run linting on new code you add to ensure it follows project standards - Install golangci-lint if needed: `go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.57.2` ## Common Tasks ### Repository Structure ``` . ├── README.md - Project documentation ├── CONTRIBUTING.md - Development guidelines ├── Taskfile.yml - Task runner configuration ├── go.mod - Go module dependencies ├── web/ - Vue.js frontend application │ ├── package.json - Frontend dependencies │ ├── src/ - Vue.js source code │ └── public/ - Static assets ├── cli/ - Go CLI application entry point ├── api/ - Go API server endpoints ├── db/ - Database models and interfaces ├── services/ - Business logic services ├── util/ - Utility functions and configuration ├── bin/ - Built binaries (after build) └── config.json - Runtime configuration (after setup) ``` ### Key Commands Reference ```bash # Install task runner go install github.com/go-task/task/v3/cmd/task@latest # Install all dependencies (backend + frontend + tools) task deps # Build application (frontend + backend) task build # Run tests task test # Run linting task lint # Setup application (interactive) ./bin/semaphore setup # Start server ./bin/semaphore server --config ./config.json # View available task commands task --list ``` ### Database Options for Development During setup, choose option 4 (SQLite) for the simplest development setup: - No external database server required - Database file stored at the path configured in `config.json` (default under `/tmp/`) - Perfect for development and testing > **Note:** BoltDB (option 2) was removed in Semaphore 2.19. If you have an existing > `database.boltdb` file, migrate to SQLite, MySQL, or PostgreSQL before upgrading. ### Frontend Development - Vue.js 2.x application in `web/` directory - Built with Vue CLI and Vuetify components - Build output goes to `api/public/` for serving by Go backend - Development server not typically used - Go server serves built assets ### Backend Development - Go application with CLI and API server - Uses Gorilla Mux for routing - Supports multiple databases: MySQL, PostgreSQL, SQLite (BoltDB was removed in 2.19) - Configuration via JSON file or environment variables ## Troubleshooting ### Build Issues - If `task` command not found: Install with `go install github.com/go-task/task/v3/cmd/task@latest` - If Go version errors: Ensure Go 1.21+ is installed - If npm install fails: Ensure Node.js 16+ is installed - If build takes too long: This is normal - frontend build can take 60+ seconds ### Runtime Issues - If server won't start: Check config.json exists and database is accessible - If web UI shows errors: Check that frontend build completed successfully in `api/public/` - If API returns errors: Check server logs for specific error messages ### Database Issues - For development, use SQLite (option 4) during setup - The SQLite database file is created automatically at the configured path - If database errors occur, remove the SQLite file and run setup again - Configs with `"dialect": "bolt"` will fail at startup — switch to `sqlite` and re-run setup ## Important Notes - **NEVER CANCEL** long-running builds or dependency installations - Set appropriate timeouts: deps (5+ min), build (3+ min), tests (2+ min) - The application serves the frontend from the Go backend - no separate frontend server needed - Configuration is stored in `config.json` after running setup - Default admin credentials after setup: admin / changeme - Linting has known issues - focus on not introducing new ones - Always test changes by running the full application, not just unit tests --- name: semaphore-checkout description: >- Create and switch to a branch with the same name in both repos — the root repo and pro_impl. Usage: /semaphore-checkout --- Create a branch named `` in both repositories at once — the root repo (current directory) and the PRO module repo (`./pro_impl`) — and switch both to it. CI depends on branch names matching: GitHub Actions clones the `pro_impl` branch with the same name as the root repo branch and falls back to `main` if it does not exist. This skill keeps the two repos in sync. ## Arguments - `` (required) — the branch to create. If not provided, ask the user for it. Validate it with `git check-ref-format --branch ` before use. ## Behavior For each repo — root (`.`) first, then `./pro_impl`: 1. Check the working tree is clean (`git status --porcelain`). If there are uncommitted changes in either repo, stop and report which repo is dirty — do not stash or discard anything. 2. Fetch the latest state: `git fetch origin`. 3. Create the branch from the up-to-date default branch and switch to it: - root repo: `git checkout -b origin/develop` - pro_impl: `git checkout -b origin/main` 4. If the branch already exists locally, just `git checkout ` instead of creating it. If it exists only on origin, check it out tracking the remote branch. Do not push the new branches — they are pushed later with the first commit. ## Rules - Never force-create (`-B`) or reset an existing branch. - Both repos must end up on the same branch name; if step for `pro_impl` fails after the root repo already switched, report the inconsistent state clearly. - Report the final state at the end: branch name and start point in each repo. ## Example ``` /semaphore-checkout fix/task-env-vars ``` Result: ``` Root repo: fix/task-env-vars (from origin/develop) pro_impl: fix/task-env-vars (from origin/main) ``` --- name: semaphore-cli-docs description: > Generate or update the CLI documentation under `docs/docs/reference/cli/` from the Cobra command code in `cli/`. Use this skill whenever the user asks to "update the CLI docs", "actualize/sync the CLI documentation", "document the CLI", "the CLI docs are out of date", "regenerate the runner/user/vault/project/migrate docs", or after adding or changing a Cobra command, subcommand, flag, alias, or required-argument check anywhere under `cli/cmd/`. Covers every command group (`users`, `projects`, `vaults`, `runner`, `migrate`) plus the operational commands (`server`, `setup`, `version`) and the global flags on the root command. Trigger when the user adds a new `*Cmd` Cobra command, a new `PersistentFlags()` call, or renames/removes a CLI flag. --- # Semaphore — CLI Documentation Generator This skill produces and maintains the CLI reference pages under `docs/docs/reference/cli/` and the CLI index `docs/docs/reference/cli/README.md`. Every page is **derived from the Cobra command code** in `cli/cmd/`. If a command, subcommand, or flag isn't in the code, it must not be in the docs; if a flag's name, default, or required-ness changed, the docs must change with it. > `docs/` is a **git submodule** (the documentation site). Editing files under `docs/docs/...` and > `docs/sidebars.js` is correct; those changes are committed to the submodule, not the main repo. The docs are the human-facing contract. The Go code is the source of truth. When they disagree, the code wins — **but** read the command's `Run` body, not just its help strings, because help text drifts (see Pitfalls). > **`docs/docs/reference/cli/commands.md` is not yours.** It is generated by `tools/clidocs`, which walks the real > Cobra tree and emits every command and flag with its Cobra help string. Run `task docs:gen` for it and never edit > it by hand. This skill owns the *task-oriented* pages next to it: what each command group is for, what the > arguments mean in practice, what the command actually does to the database, and worked examples. Do not try to > reproduce an exhaustive flag inventory here — link to `/reference/cli/commands` instead and spend the words on > behaviour the help strings cannot express. ## Inputs (source of truth) Read these in full before writing. Each command group maps to exactly one page. | Source files (`cli/cmd/`) | Doc page | |---------------------------|----------| | `root.go` | `docs/docs/reference/cli/README.md` — global flags, command overview | | `server.go`, `setup.go`, `version.go` | `docs/docs/reference/cli/README.md` — operational commands | | `user.go`, `user_add.go`, `user_change.go`, `user_delete.go`, `user_get.go`, `user_list.go`, `user_token.go`, `user_totp.go` | `docs/docs/reference/cli/users.md` | | `project.go`, `project_export.go`, `project_import.go` | `docs/docs/reference/cli/projects.md` | | `vault.go`, `vault_check.go`, `vault_rekey.go` | `docs/docs/reference/cli/vaults.md` | | `runner.go`, `runner_register.go`, `runner_setup.go`, `runner_start.go`, `runner_unregister.go` | `docs/docs/reference/cli/runners.md` | | `migrate.go` | `docs/docs/reference/cli/migrations.md` | `*_test.go` files (e.g. `runner_register_test.go`, `user_token_test.go`) encode exact behavior — read them to document precise rules (e.g. registration-token resolution order, token expiry formatting). `syslog.go` / `syslog_windows.go` are internal helpers, **not** commands — never document them. Re-discover the command tree before each run; don't trust this table if files were added/removed: ```bash ls cli/cmd/*.go | grep -v _test grep -rn "cobra.Command{" cli/cmd/ | grep -v _test # every command/subcommand grep -rn "AddCommand\|PersistentFlags()\." cli/cmd/ # wiring + flags ``` ## How to read a Cobra command Extract these facts mechanically from each `*Cmd = &cobra.Command{...}` and its `init()`: - **Command name** — the `Use:` field (first word). Subcommands are wired with `parent.AddCommand(child)`. - **Aliases** — the `Aliases:` slice. Document them (e.g. `users`/`user`, `projects`/`project`, `vaults`/`vault`, `server`/`service`). A command whose `Run` only calls `cmd.Help()` is a pure group — it has no behavior of its own, just subcommands. - **Flags** — each `cmd.PersistentFlags().Var(&arg, "name", default, "usage")` becomes one table row: flag = `--name`, description from the usage string, and note the default when it's meaningful (e.g. `--enabled` defaults to `true`, `--project-id` defaults to `0` = "global"). `StringSliceVar` → "comma-separated or repeat the flag". - **Required / mutually-exclusive args** — read the `Run` body. Patterns like `if args.x == "" { fmt.Println("Argument --x required"); ok = false }` mean **required**; checks that reject setting both of two flags mean **exactly one of**. Document these rules explicitly ("Exactly one of `--a` or `--b` is required"). - **Output** — what the command prints on success (IDs, a table, nothing). Mirror the real `fmt.Printf` format in the doc, including example output blocks for commands that print structured results (e.g. `vault check`). ### Global flags (from `root.go`) Documented once in `cli.md`; they apply to every command. Currently: `--config`, `--no-config`, `--log-level` (`DEBUG|INFO|WARN|ERROR|FATAL|PANIC`, env `SEMAPHORE_LOG_LEVEL`), `--debug-filter` (DEBUG-only namespace filter, env `SEMAPHORE_DEBUG_FILTER`). Re-read `Execute()` in `root.go` for the live list. ## Page structure (match the existing style) Every command-group page follows the shape established in `users.md` and `vaults.md`: 1. `# ` then a one-sentence purpose. 2. A fenced `semaphore <group> --help` block. 3. An alias note as a `>` blockquote when the group has an alias (`> \`vault\` is an alias for \`vaults\`.`). 4. A subcommand table (`| Command | Purpose |`) with in-page anchor links when the page is long. 5. One `##` section per subcommand: a short description, a copy-pasteable example, then a `| Flag | Description |` table. State required/exactly-one rules in prose under the table. Conventions: - Internal links are absolute from the route base `/`: **`/reference/cli/<page>`** (NOT `/cli/<page>` — that base is wrong and 404s). Cross-links to concept pages use the same form, e.g. `/admin-guide/runners`, `/admin-guide/security/encryption`. - Admonitions use Docusaurus syntax: `:::tip`, `:::warning` … `:::`. - Keep prose task-oriented and match the tone/heading depth of neighboring pages. ## Index page (`cli.md`) and sidebar - `cli.md` carries: intro + `semaphore help`, a command-group table linking to each page, the **global options** table, and short sections for `version`, `setup`, `server`, `runner`, `migrate`. - Every command-group page must be registered in **`docs/sidebars.js`** under the `label: 'CLI'` category's `items` array, as `'reference/cli/<page>'`. Adding a page without registering it hides it from navigation. ## Workflow ### 1. Enumerate the live command tree Run the discovery greps above. Build the set of command groups and subcommands that actually exist. Note any group/subcommand/flag that has no corresponding doc section, and any doc section with no corresponding code. ### 2. Extract facts per command For each command, pull name, aliases, flags (name/default/usage), required/exclusive rules (from `Run`), and success output. Cross-check `*_test.go` for exact behavior. ### 3. Update each page Rewrite or patch each page so it matches the extracted facts and the page structure above. Add sections for new subcommands; remove sections for deleted ones; fix flag tables. Leave a page untouched only after confirming it already matches the code. ### 4. Update the index and sidebar Refresh `cli.md` (command table, global options, operational commands) and ensure every page is listed in `docs/sidebars.js`. ### 5. Build to catch broken links From the `docs/` directory: ```bash cd docs && npm run build 2>&1 | tail -40 ``` The build must end with `[SUCCESS] Generated static files`. **Broken-link** errors in pages you touched must be fixed. Pre-existing **broken-anchor** warnings in unrelated pages (e.g. `admin-guide/configuration`, `admin-guide/installation_manually`) are not yours to fix — note them and move on. If `node_modules` is absent, run `npm install` first (or tell the user the build couldn't run). ## Pitfalls - **Dead flags.** A flag registered in `init()` but never read in the command's `Run` does nothing — do not document it as functional. Example: after BoltDB removal, `migrate` still registers `--err-log-size`, `--skip-task-output`, `--merge-existing-users`, but `Run` only uses `--apply-to` / `--undo-to`. Verify each flag is actually consumed before documenting it. - **Removed features → version-gate, don't silently delete.** When a command/flag is removed (e.g. `migrate --from-boltdb`; BoltDB is "not supported starting from 2.19" per `cli/setup/setup.go`), keep the guidance but mark the version boundary with a `:::warning`, so users on older versions are still served. Note when other parts of the repo (e.g. `deployment/docker/server/server-wrapper`) still reference a removed flag — that's a stale call site worth flagging to the user, but out of scope for the docs change. - **Stale help strings.** A command's `Short`/`Long` text can lag the code. Verify config-key names against the actual structs in `util/` (e.g. `vault rekey`'s `--old-key` help says `access_key`, but the real config field is `secret_key` / `secret_key_file` in `util/config.go`). Document the struct, not the help string. - **Group commands have no flags of their own.** `users`, `projects`, `vaults`, `runner`, `token`, `totp` just print help and dispatch to subcommands. Don't invent flags for them. - **Don't document the internal `server` runtime.** `server.go`/`root.go` wire a lot of services; the doc only needs "start the server, `service` is an alias, respects global flags." ## When to ask or refuse - If a command's behavior is genuinely ambiguous from the code (e.g. a flag is read but its effect spans packages you can't quickly trace), summarize what you found and ask the user rather than guessing. - If asked to document a flag or command that **doesn't exist in `cli/cmd/`**, refuse and explain: CLI docs are generated from the Cobra code — add the command/flag first, then regenerate. - Before deleting a whole documented section (a removed command group), propose it explicitly; prefer version-gating over silent removal when older releases still ship the feature.  --- name: semaphore-commit --- Create well-formatted git commits following conventional commit standards. ## Behavior 1. Analyze staged changes with `git diff --staged` 2. Generate a conventional commit message 3. Create the commit with proper formatting 4. Do not add "Co-Authored-By: Claude ... <noreply@anthropic.com> to the footer" ## Commit Format ``` <type>(<scope>): <description> [optional body] [optional footer] ``` ## Types - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes - refactor: Code refactoring - test: Adding or modifying tests - chore: Maintenance tasks - agents: Changes related to AI agents work ## Example Output ``` feat(auth): add password reset functionality - Add forgot password form - Implement email verification flow - Add password reset endpoint ```  --- name: semaphore-config-schema description: > Generate or update the JSON Schema (in YAML form) that describes the Semaphore configuration file. The schema lives at `config.schema.yaml` in the repository root and is derived from the Go struct `util.ConfigType` (with nested types in `util/config.go`, `util/config_auth.go`, `util/App.go`, `util/OdbcProvider.go`). Use this skill whenever the user asks to "regenerate the config schema", "update config.schema.yaml", "sync the schema with ConfigType", "add a new field to the schema", "the schema is out of date", or after a Go struct change that affects configuration. Also trigger when the user adds a new top-level field, new nested struct, or changes a `json:`, `default:`, `rule:`, or `env:` tag on a config struct field. --- # Semaphore — Config Schema Generator This skill produces and maintains `config.schema.yaml` — a **JSON Schema draft 2020-12** document (written in YAML) describing every valid key in a Semaphore `config.json` / `config.yaml`. The schema is the source of truth for IDE autocomplete (via `yaml-language-server`) and for any future server-side config validation. The schema is **derived from Go code**, never hand-edited speculatively. If `ConfigType` doesn't have a field, the schema must not have it. If a field has a `default:` or `rule:` tag, the schema must reflect it. ## Inputs (source of truth) All Go types live in the `util` package. Read these files **in full** before writing anything: | File | What's in it | |------|--------------| | `util/config.go` | `ConfigType` (root) + most nested types: `DbConfig`, `TLSConfig`, `RunnerConfig`, `TotpConfig`, `EventLogType`, `TaskLogType`, `ConfigLog`, `SyslogConfig`, `ConfigProcess`, `ConfigAppNamespaces`, `ScheduleConfig`, `DebuggingConfig`, `HAConfig`, `HARedisConfig`, `TeamsConfig`, `ConfigDirs`, `SubscriptionConfig`, `LdapMappings`, `oidcEndpoint` | | `util/config_auth.go` | `MultifactorAuthConfig`, `EmailAuthConfig`, `TotpConfig`, `RecaptchaConfig` | | `util/App.go` | `App` | | `util/OdbcProvider.go` | `OidcProvider` (note: filename is `Odbc...`, typo'd — don't "fix" it) | If a struct moves or a new file appears, find it with: ```bash grep -rn "^type .* struct" util/ | grep -v _test ``` ## Output A single file: **`config.schema.yaml`** in the repository root. Header (top of file) — keep exactly this shape: ```yaml $schema: "https://json-schema.org/draft/2020-12/schema" $id: "https://semaphoreui.com/schemas/config.schema.json" title: Semaphore configuration description: Schema for Semaphore UI config.json / config.yaml. Generated from util.ConfigType. type: object ``` ## Field-mapping rules These are non-negotiable — apply them mechanically. ### Property name Use the **`json:` tag's first segment** (before any comma): ```go Port string `json:"port,omitempty" ...` // → property name "port" ``` Skip fields where the `json:` tag is `"-"` (e.g. `RunnerConfig.RegistrationToken`, `SubscriptionConfig.Key` — those are env-only, not file-configurable). Document this in the schema's `description` for the containing struct if a sensitive token is reachable only via env. Skip unexported fields (lowercase first letter) — but include their **referenced types** if they appear via exported fields. Example: `oidcEndpoint` is unexported but referenced from `OidcProvider.Endpoint`, so define it under `$defs` as `OidcEndpoint`. ### JSON Schema `type` | Go type | Schema type | |---------|-------------| | `string` | `string` | | `bool` | `boolean` | | `int`, `int64`, `uint32` | `integer` | | `float64` | `number` | | `[]T` | `array`, with `items: { ... }` | | `map[string]T` | `object`, with `additionalProperties: { ... }` | | `*T` (pointer) | same as `T`. If `*int`, allow `null`: `type: [integer, "null"]` | | `*Struct` | `{ $ref: "#/$defs/Struct" }` | ### Constraints from tags - **`default:"X"`** → emit `default: X` (cast to the right type — `default:"10"` on `int` becomes `default: 10`). - **`rule:"^...$"`** → emit `pattern: "^...$"`. **Don't** also add a `format:` — the regex is more authoritative. - **`env:"NAME,sensitive"`** → append `(sensitive).` to the `description`. The schema doesn't have a native "sensitive" flag, so this is documentation-only. - **`env:"NAME"`** without `sensitive` → no change to schema. - URL-looking string fields (web hooks, redirect URLs) → add `format: uri` **unless** a `pattern` is already set from a `rule:` tag. ### `enum` discovery `enum` is not always in tags — sometimes it's in code: 1. Check for a `rule:"^a|b|c$"` regex — convert that to `enum: [a, b, c]` instead of a pattern (more useful in IDE). 2. Check for typed constants near the struct (e.g. `SyslogFormat` has `SyslogDefault = ""` and `SyslogRFC5424 = "rfc5424"` → `enum: ["", rfc5424]`). 3. `TeamInviteType` constants (`TeamInviteEmail`, `TeamInviteUsername`, `TeamInviteBoth`) → enum. ### Reusable types → `$defs` Every named struct that appears as a field type gets a `$defs/<TypeName>` entry. Reference via `$ref: "#/$defs/<TypeName>"`. Top-level `properties` should reference, not inline. Exception: `lumberjack.Logger` is external — define a minimal stub `$defs/LumberjackLogger` with the common fields (`filename`, `maxsize`, `maxage`, `maxbackups`, `localtime`, `compress`). Do not try to fully model it. ### `additionalProperties` Leave it **unset** (defaults to `true`). The schema is informational, not strict — making it strict would break existing configs that have stray keys (legacy fields, typos used as comments, etc.). ## Workflow ### 1. Read all four Go files Use `Read` on each file. Do not skim. Note every exported field on every struct. ### 2. Build a mental map: struct → properties For `ConfigType` (the root), list every exported field with its `json:` name, Go type, and any `default:` / `rule:` / `env:` tags. Then for each referenced struct, do the same. Stop when no new structs appear. ### 3. Diff against existing `config.schema.yaml` Before writing, compare what Go has vs. what the schema has: ```bash # List all json tag names in Go grep -hoE 'json:"[^,"]+' util/*.go | sed 's/json:"//' | sort -u > /tmp/go-keys.txt # List all property keys in the schema yq '.properties | keys | .[]' config.schema.yaml | sort -u > /tmp/schema-keys.txt diff /tmp/go-keys.txt /tmp/schema-keys.txt ``` Identify three categories: - **In Go, missing from schema** → add. - **In schema, missing from Go** → remove (the Go struct is the source of truth). - **In both** → check that type / default / pattern still match. Show the user the diff before applying changes if it's larger than ~5 lines. ### 4. Write `config.schema.yaml` Use the **YAML formatting conventions** already established in the file: - Section comments split top-level `properties` into visual groups: `# === Database ===`, `# === HTTP server ===`, `# === Authentication ===`, etc. - Inline-object syntax `{ type: string, default: foo }` for one-property entries. - Multi-line block form when there are 3+ properties or a `description`. - Quote string values that contain `:`, `/`, `+`, `=`, or start with a digit. Don't quote bare identifiers like `string`, `boolean`, `integer`. - `$ref` values are quoted: `{ $ref: "#/$defs/DbConfig" }`. ### 5. Validate After writing, run two checks: ```bash python3 - <<'PY' import yaml, jsonschema with open("config.schema.yaml") as f: schema = yaml.safe_load(f) jsonschema.Draft202012Validator.check_schema(schema) # meta-validation print("schema is valid") # Confirm an existing config.yaml still passes try: with open("config.yaml") as f: cfg = yaml.safe_load(f) errors = list(jsonschema.Draft202012Validator(schema).iter_errors(cfg)) print(f"config.yaml: {len(errors)} error(s)") for e in errors: print(f" {list(e.path)}: {e.message}") except FileNotFoundError: pass PY ``` Both must pass. If `config.yaml` doesn't exist locally, skip the second check — the meta-validation alone is sufficient. ### 6. Don't touch `config.yaml` The user's `config.yaml` may contain stray legacy keys or comments. Do not "clean it up" as part of this skill — the schema generation is a one-way operation Go → schema. If the user wants a cleaner config, that's a separate task. ## Common pitfalls - **`json:"-"` fields**: easy to accidentally include. Always check the tag, not the field name. - **Pointer vs. value**: `*int` is nullable, plain `int` is not. Reflect that in `type`. - **Typo'd filenames**: `util/OdbcProvider.go` (should be `Oidc`) — preserve it; renaming files is out of scope. - **Tag inheritance illusion**: nested structs don't inherit tags from their parent field. The `default:` on `ConfigType.MaxParallelTasks` is on the field, not on `int`. - **`sensitive` is not standard**: JSON Schema has no built-in sensitive marker. Encode it in `description` text only. - **Existing keys with apostrophes** in `config.yaml` (e.g. `"'email_sender"`) are user-side comment hacks — ignore them, they're not in any Go struct. ## When to refuse If the user asks to add a property to the schema that **doesn't exist in `ConfigType`** ("just add a `foo` field so my config validates"), refuse and explain: the schema is generated from Go. The fix is to add the field to the Go struct first, then regenerate. If `ConfigType` has been heavily refactored and a previous schema entry no longer maps, propose the deletion explicitly before doing it — never silently drop entries that the user might have been relying on.  # License Policy for Semaphore UI This is the source of truth for which open-source licenses are acceptable in Semaphore UI dependencies. The policy is enforced by `scripts/check_policy.py` — if you change anything here, mirror the change in that script. The policy exists for two reasons: 1. **Customer obligations.** Our MSA commits us to *not* shipping components on terms that would require customers to license or assign their IP. That rules out copyleft licenses with strong reciprocity (GPL family, AGPL, SSPL). 2. **Project sustainability.** Source-available-but-not-OSS licenses (BUSL, Commons Clause, Elastic 2.0) carry use restrictions that conflict with our open-source distribution model. ## Allowed (no review needed) These are permissive licenses with attribution-only obligations. Anything under one of these can be added without further discussion. | SPDX ID | Name | |---------|------| | MIT, MIT-0 | MIT License | | Apache-2.0 | Apache License 2.0 | | BSD-2-Clause | BSD 2-Clause "Simplified" | | BSD-3-Clause | BSD 3-Clause "New" | | ISC | ISC License | | Zlib | zlib License | | Unlicense | The Unlicense | | CC0-1.0 | Creative Commons Zero | | MPL-2.0 | Mozilla Public License 2.0 (file-level copyleft, OK for libraries) | | 0BSD | BSD Zero Clause | | BlueOak-1.0.0 | Blue Oak Model License | | Python-2.0 | Python Software Foundation License | **Note on MPL-2.0:** MPL is allowed because its copyleft obligation is at the *file* level, not the project level. We can use MPL-licensed libraries without making Semaphore UI MPL. If we ever modify an MPL-licensed file, that file must remain MPL. ## Review required These licenses are not blanket-forbidden but require a case-by-case decision. Pause and ask before merging a dependency under one of these. | SPDX ID | Why review | |---------|------------| | LGPL-2.1, LGPL-3.0 (and `-or-later`) | LGPL is fine for **dynamic** linking, but Go statically links by default. An LGPL Go library would force us to provide object files so users can relink. Acceptable only if the library is genuinely irreplaceable and we can document the relinking pathway. | | EPL-1.0, EPL-2.0 | Eclipse Public License has weak copyleft and an explicit patent clause. Generally workable but worth a legal eyeball. | | CDDL-1.0, CDDL-1.1 | File-level copyleft like MPL, but with extra requirements. Rare in our ecosystem. | | EUPL-1.1, EUPL-1.2 | European Union Public License. Compatible with several other licenses; check the specific version. | | OFL-1.1 | SIL Open Font License. Almost always fine for embedded fonts, but verify the font is being used as intended (not redistributed standalone with a new name). | ## Forbidden A dependency under one of these licenses **must not be added**. If `check_policy.py` flags one, the options are: (a) remove it, (b) replace it with a permissively-licensed alternative, (c) move the functionality out of process (subprocess invocation breaks the linkage in most cases — this is why Ansible is acceptable). | SPDX ID | Why forbidden | |---------|--------------| | GPL-2.0, GPL-3.0 (and `-only` / `-or-later`) | Strong copyleft. Linking forces Semaphore UI to be GPL, which conflicts with our distribution model. | | AGPL-1.0, AGPL-3.0 | Same as GPL plus a network-interaction trigger. Particularly hostile to SaaS/self-hosted server software. | | SSPL-1.0 | MongoDB's Server Side Public License. Not OSI-approved; imposes obligations on anyone offering the software as a service. | | BUSL-1.1 | Business Source License. Time-delayed open source with use restrictions during the change window. Not OSS. | | Commons-Clause | Restricts commercial sale; strips OSS status from any underlying license it's attached to. | | Elastic-2.0 | Elastic License v2. Use restrictions; not OSS. | | RSALv2 | Redis Source Available License v2. Same family as BUSL/Elastic. | | CC-BY-NC-* | Creative Commons "Non-Commercial" variants. Not usable in a commercially-distributable product. | | Facebook-BSD-Patents (legacy) | The old React patent grant clause. Removed years ago, but flagged here as a defensive measure. | ## Subprocess exception (External Runtime Tools) Tools that Semaphore UI invokes via `os/exec` (Ansible, Terraform, OpenTofu, Pulumi, Bash) are NOT linked into our binary and NOT redistributed by us. Their licenses govern the user's installation of those tools on the host system, not our distribution. This is why we can integrate with Ansible (GPL-3.0) and Terraform (BUSL-1.1) without violating this policy — we never embed their code, we only document that the user must install them separately. These tools are intentionally **not listed** in `THIRD-PARTY-LICENSES.md`. Listing them would wrongly imply that they are distributed with the product and would invite unnecessary scrutiny from a customer's legal team. Neither `collect_licenses.sh` nor `generate_md.py` produces or accepts an external- tools section. ## When the policy itself needs to change If a dependency we genuinely need is forbidden, the path forward is: 1. Document the technical need (what does it do, what alternatives exist). 2. Get sign-off from a maintainer with the authority to make that call. 3. Update **both** this document and `check_policy.py`, in the same commit. 4. Note the exception in `THIRD-PARTY-LICENSES.md` so customers can see it. Don't relax the policy silently. The whole point is that customers can audit us, so the policy must be auditable too.  # THIRD-PARTY-LICENSES.md output format This is the canonical structure that `scripts/generate_md.py` produces. Reference for humans reviewing the generator output, and for anyone who needs to understand what each section is for. ## Structure ``` # Third-Party Licenses [intro paragraph explaining what this file is and why it exists] _Generated on YYYY-MM-DD HH:MM UTC by scripts/collect_licenses.sh._ [regeneration instructions — always include these so the file is reproducible by anyone, not just the original author] ## Summary [total component count] | Ecosystem | Components | |-----------|------------| | Go (backend) | NN | | npm (frontend) | NN | ### License distribution | License | Count | |---------|-------| | MIT | NN | | Apache-2.0 | NN | | BSD-3-Clause | NN | | ... | NN | ## Go Backend Dependencies [one-line description of what these are and where they come from] | Component | Version(s) | License | Source | |-----------|------------|---------|--------| | `github.com/foo/bar` | v1.2.3 | MIT | [link](https://...) | | `github.com/foo/baz` | v0.4.1, v0.5.0 | Apache-2.0 | [link](https://...) | | ... ## Frontend Dependencies (npm) [one-line description] | Component | Version(s) | License | Source | |-----------|------------|---------|--------| | `vue` | 3.4.21 | MIT | [link](https://...) | | `vuetify` | 3.5.8 | MIT | [link](https://...) | | ... --- ## License texts [paragraph explaining where to find full license texts and how to report missing/incorrect attributions]  ``` ## Why this structure **Summary table at the top.** Lets a reader (especially a customer's compliance team) see the shape of the dependency tree at a glance without scrolling through hundreds of rows. **License distribution.** Surfaces concentration risk. If 95% of deps are MIT/Apache and 1 is MPL-2.0, that 1 deserves attention. It also makes it easy to spot a forbidden license that somehow slipped through (a single GPL-3.0 row in the distribution table is a very loud red flag). **Sorted alphabetically within each section.** Diffs between releases become useful — a new dependency shows up as an added row in one predictable place, not scattered across the file. **Versions collapsed onto one line.** A dependency pinned at multiple versions (common with transitive Go deps that get MVS-resolved differently in different parts of the tree) shouldn't take 5 rows. One row, comma- separated versions. **External tools deliberately excluded.** Ansible, Terraform, OpenTofu, Pulumi, and Bash are invoked as subprocesses, not linked, and not redistributed with Semaphore UI. They are not listed in this file — including them would wrongly imply distribution. The license policy document covers them under "Subprocess exception" if a reviewer asks why they're absent. **Regeneration instructions in the header.** Means the file is not a hand-maintained artifact that drifts. Anyone can rebuild it and verify it matches what's actually in the dependency manifests. **Footer comment marker.** `` lets CI verify the file wasn't truncated mid-write — useful when generation runs in a pipeline and might fail partway. ## What NOT to include - **Full license texts inline.** Don't copy the MIT license text 200 times into one file. Refer readers to the source URL. The packages themselves carry their LICENSE files; the user has them on disk after `go mod download` / `npm install`. - **CVE / vulnerability info.** That belongs in security advisories, not the license document. Mixing the two confuses the reader and makes the file go stale faster. - **Internal-only dependencies.** Build tooling (linters, test frameworks, code generators) doesn't ship to customers. Production dependencies only. - **Hand-edited rows.** If something needs a special note, add it via the generator (extend `generate_md.py`), not by editing the output file. Hand edits get destroyed on the next regeneration.  --- name: semaphore-third-party-licenses description: > Generate or update the THIRD-PARTY-LICENSES.md file for the Semaphore UI repository. Use this skill whenever the user asks to create, update, regenerate, audit, or refresh third-party license attributions, OSS notices, SBOM-style license inventories, or NOTICE files for Semaphore UI. Trigger on phrases like "third-party licenses", "OSS notices", "license attribution file", "SBOM for licenses", "NOTICE file", "audit dependencies", "licenses for go.mod / package.json", or any request that mentions compliance with customer agreements requiring an OSS components list. Also trigger when the user says "we added a new dependency, regenerate licenses". This skill knows the Semaphore UI layout (Go backend + Vue.js frontend), the project's license policy (allowlist/denylist), and the canonical output format. --- # Semaphore UI — Third-Party License Generator This skill produces `THIRD-PARTY-LICENSES.md` for the Semaphore UI repository. The file lists every open-source dependency shipped with Semaphore UI by **name**, **version**, **license**, and **source URL**, grouped by component. It exists to satisfy contractual obligations toward customers (identification of OSS components by name, version, and license type) and to preserve attribution required by permissive licenses (MIT/BSD/Apache-2.0). ## Repository layout you can expect Semaphore UI is a self-hosted product. The repository ships: - **Go backend** — module file at `go.mod`, source under `pkg/`, `services/`, `db/`, etc. - **Vue.js frontend** — `web/package.json` (or `web2/package.json` in some branches), built into static assets and embedded in the Go binary. External CLI tools (Ansible, Terraform, OpenTofu, Pulumi, Bash) are invoked at runtime as separate operating-system processes. They are NOT linked into the binary and NOT redistributed with Semaphore UI, so they are intentionally **not listed** in `THIRD-PARTY-LICENSES.md` — their license terms apply to the user who installs them on the host, not to Semaphore UI's distribution. The license policy still discusses why this is contractually safe (see `references/license_policy.md`, "Subprocess exception"). If the layout differs (monorepo restructure, new submodule, etc.), inspect the repo first with `find . -name "go.mod" -o -name "package.json" -not -path "*/node_modules/*"` and adapt. ## Workflow Follow these steps in order. Don't skip the policy check — it's the part that actually protects the project from accidentally shipping a GPL'd dependency. ### 1. Confirm scope with the user Before generating anything, ask (briefly) which targets to include if it's not obvious from context: - Backend only? Frontend only? Both? - Production dependencies only, or also dev dependencies? **Default**: both backend and frontend, **production-only** (dev dependencies are not distributed to customers and don't need attribution). Override only if the user explicitly asks for dev deps too. ### 2. Collect raw license data Run `scripts/collect_licenses.sh` from the repo root. It does the following: - Sets `GOWORK=off` and runs `go-licenses report ./... --template scripts/go_template.tpl` for the Go backend, so workspace siblings (e.g. `pro_impl`) are not pulled in. - Rolls sub-package rows up to their parent module (uses `go list -m all` for the module → version map) and drops any module path that belongs to the root module's namespace (first-party packages, including `replace … => ./pro` targets). - Applies a small `OVERRIDES` table in the script for modules where `go-licenses` can't auto-detect a license (e.g. `modernc.org/mathutil` → BSD-3-Clause). Extend the table when new "Unknown" entries appear. - Runs `license-checker --production --json --excludePrivatePackages` in the frontend directory and strips the low-confidence `*` suffix from license strings so `MIT*` collapses into `MIT`. - Writes raw output to `.licenses-cache/go.tsv` and `.licenses-cache/npm.json`. If the tools aren't installed, the script prints the install commands. Don't try to install them silently — show the user what needs to be added so they can decide whether to add them to CI. ### 3. Run the policy check Run `scripts/check_policy.py .licenses-cache/`. This compares every detected license against the project policy in `references/license_policy.md`: - **Allowed** (green): MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, Zlib, Unlicense, CC0-1.0, MPL-2.0 — proceed. - **Review** (yellow): LGPL-2.1, LGPL-3.0, EPL-2.0, CDDL-1.0, custom/unknown — pause and ask the user. LGPL is fine for dynamic linking but Go statically links, so flag it for review. - **Forbidden** (red): GPL-2.0, GPL-3.0, AGPL-3.0, SSPL-1.0, BUSL-1.1, Commons Clause, "non-commercial" clauses — STOP. Do not proceed with file generation. Report the offending package and ask the user how to handle it (replace, vendor, or accept and document the consequence). **This step is non-negotiable.** A forbidden license slipping into THIRD-PARTY-LICENSES.md isn't just a documentation problem — it's a contract breach with every customer. If `check_policy.py` returns a non-zero exit code, surface the failures prominently and stop. ### 4. Generate the markdown Run `scripts/generate_md.py .licenses-cache/ > THIRD-PARTY-LICENSES.md`. This produces the file using the structure described in `references/template.md`. Key points the generator handles: - Sorts entries alphabetically within each section. - Groups by component category (Go backend / npm frontend). - Deduplicates packages that appear at multiple versions (lists all versions on one line). - Renders a summary table at the top with license counts. - Adds a generation timestamp and a note pointing to `scripts/collect_licenses.sh` so the file is reproducible. ### 5. Verify and commit After generation: 1. Diff against the previous `THIRD-PARTY-LICENSES.md` (if it exists). New rows = new dependencies — confirm with the user that they're expected. 2. Verify the file isn't truncated and ends with the closing footer (``). 3. Suggest the commit message: `chore(licenses): regenerate THIRD-PARTY-LICENSES.md for vX.Y.Z`. 4. If a CI pipeline exists (`.github/workflows/`), suggest adding a job that runs `scripts/check_policy.py` on every PR — that's how the project prevents regressions, not by re-checking manually each release. ## Notes on edge cases **Vendored dependencies.** If the repo has a `vendor/` directory, `go-licenses` will read from it. That's fine — vendored code still ships and still needs attribution. **Dual-licensed packages.** Some packages are offered under "MIT OR Apache-2.0". Pick MIT (the simpler one) and note the choice in the entry: `License: MIT (also available under Apache-2.0)`. **Packages with no detectable license.** `go-licenses` flags these as "Unknown". Don't ship the file with Unknowns — manually inspect the repo, fill in the SPDX identifier, and if there's truly no license, treat the package as forbidden (no license = "all rights reserved", which is incompatible with redistribution). **Ansible / Terraform / OpenTofu / Pulumi / Bash.** Do NOT list them in `THIRD-PARTY-LICENSES.md`. They are invoked as separate OS processes (`os/exec`), not linked, not redistributed. Their licenses bind the user who installs them on the host, not Semaphore UI's distribution. Listing them would imply otherwise and is an unnecessary signal to a reviewing customer's legal team. The "Subprocess exception" section in `references/license_policy.md` explains the reasoning if a reviewer asks. **First-party packages with no LICENSE.** The root module and any `replace … => ./<dir>` target (e.g. `./pro`) live inside this repo and don't need to be self-attributed. The collection script filters them out by the root module prefix from `go.mod`. If you see "Unknown license" rows for `github.com/<this-org>/<this-repo>/…`, the filter is working correctly — those rows shouldn't appear in the final cache. **Embedded license texts.** For packages under MIT/BSD/ISC, the license requires preserving the copyright notice. The generator embeds the full LICENSE file text from each package's source. For Apache-2.0 packages, it embeds the NOTICE file if one exists. ## What this skill does NOT do - It does not generate a CycloneDX or SPDX SBOM. If the user wants a machine-readable SBOM (for compliance scanners, customer attestations, etc.), point them at `syft packages dir:. -o cyclonedx-json` as a separate step. THIRD-PARTY-LICENSES.md is the human-readable artifact. - It does not check for CVEs. That's a security concern, not a licensing one — use `govulncheck` and `npm audit` for that. - It does not modify go.mod or package.json. The skill is read-only with respect to the dependency manifests; it only generates the attribution document. See `references/license_policy.md` for the full policy and `references/template.md` for the output format.  # db-query Ad-hoc SQL runners for the project's local databases — **one script per database**. Each runs the query as that database's app user, read-only by default, and logs every query it runs. | Script | Engine | Mode | Database | `.env` file | `.env` keys | Access | | --- | --- | --- | --- | --- | --- | --- | | `query_<db>.sh` | PostgreSQL / MariaDB | docker / host | `<database>` | `<path>` | `DB_*` | read-only | ## Setup None. Each script reads its connection from the project's own `.env`; the path to it is `ENV_FILE` in the script's settings block. Credentials are never copied into this folder. ## Usage ~~~shell AGENTS/tools/db-query/query_<db>.sh "SELECT id, email FROM users LIMIT 5" AGENTS/tools/db-query/query_<db>.sh -f report.sql echo "SELECT 1" | AGENTS/tools/db-query/query_<db>.sh AGENTS/tools/db-query/query_<db>.sh "SELECT ..." -t -A # trailing flags go to psql / mariadb ~~~ ## Log Every query is appended to `AGENTS/tools/db-query/log/queries.log` before it runs — timestamp, script, target, database, user, access mode, the SQL — and its exit code after. Result rows are not logged. The folder is gitignored. ## Traps - ⚠️ Local only: a remote docker daemon or a non-loopback host is refused. `ALLOW_REMOTE=1` in a script is set only on the user's explicit request — record who asked and when here. - ⚠️ Read-only by default: the session refuses any write (`READ_ONLY=1`). It guards against accidents, not against intent — SQL can switch it off. `READ_ONLY=0` in a script is set only on the user's explicit request — record who asked and when here.  # docs — portable standard by zone Approaches and conventions that would serve another project, not this project's own facts. One folder per zone, each with its own `INDEX.md`. This file routes to a zone; the zone's index routes to the doc. ## Zone index (example) The rows below are example data, illustrating the shape a real routing table takes; replace them once an actual zone exists. | When you need it | Read | | --- | --- | | Example: Writing backend code: models, routes, permissions, entity codes | `backend/INDEX.md` | | Example: Running or writing backend tests — mandatory before the first command | `backend/INDEX.md` | | Example: Editing the frontend: app layout, import boundaries, i18n | `frontend/INDEX.md` | | Example: Setting up a local stack: reverse proxy, HMR behind a proxy, tunnels — the approach, not this project's ports | `infra/INDEX.md` | | Example: Editing an env file or another human-read file: grouping, order, language, line length | `standards/INDEX.md` |  # wf-stand — run and verify workflows on the local stand Drives the agent's throwaway Semaphore stand (`http://localhost:3100`, admin/admin123, project 1, Pro build from HEAD) to execute a workflow end to end and follow every node to a terminal status. Exists because a workflow run is asynchronous: tasks, approvals and delays resolve over time and only the run-details endpoint shows all of them together. Call forms (from the repository root): ``` AGENTS/tools/wf-stand/stand.sh {start|stop|restart|build|status|log [n]} AGENTS/tools/wf-stand/seed.sh AGENTS/tools/wf-stand/seed-outputs.sh # PROJECT_NAME="…" to seed another project AGENTS/tools/wf-stand/run.sh <workflow_id> [--approve|--reject] [--stop-after SEC] [--expect success|failed|stopped] [--timeout SEC] [--run ID] AGENTS/tools/wf-stand/runner.sh {start|stop|status|tag|untag} # PID=<project> TAG=<tag>; remote runner for the stand AGENTS/tools/wf-stand/inputs.sh <workflow_id> [run_id] # outputs stored per producer + "INPUT name=value" lines per consumer NODE_PATH=~/.npm/_npx/9833c18b2d85bc59/node_modules node AGENTS/tools/wf-stand/shoot-run.cjs <workflow_id> [run_id] [out.png] [--dark] AGENTS/tools/wf-stand/seed-docs.sh # project "Demo Stand" + workflow "Build and deploy" for the docs screenshots AGENTS/tools/wf-stand/seed-survey.sh # workflow "Survey: workflow variables" (survey + node bindings) in the seed-outputs project NODE_PATH=… node AGENTS/tools/wf-stand/shoot-editor.cjs <workflow_id> [node_title] [out.png] [--dark] # editor with a node selected: survey panel, canvas, bindings NODE_PATH=… node AGENTS/tools/wf-stand/shoot-run-dialog.cjs <workflow_id> [out_dir] [--dark] # starts a run through the survey dialog; shoots the dialog and the run view's Variables strip PID=<project> WF=<workflow> NODE_PATH=… node AGENTS/tools/wf-stand/shoot-docs.cjs # the four screenshots of workflows.md § Outputs and inputs ``` Examples: ``` $ AGENTS/tools/wf-stand/stand.sh build && AGENTS/tools/wf-stand/stand.sh start stand: up at http://localhost:3100 (pid 40366) $ AGENTS/tools/wf-stand/seed.sh workflows happy=5 branches=6 # ids also in /tmp/semaphore-stand/wf-exec-ids.txt $ AGENTS/tools/wf-stand/run.sh 5 --approve --expect success run 4 started (workflow 5) — UI: http://localhost:3100/project/1/workflows/5/runs/4 17:30:14 approval version=0.1.0 n18/task=task#6:success n19/approval=approval:pending n20/delay=- n21/task=- 17:30:14 node 19 -> approved 17:30:24 success version=0.1.0 n18/task=task#6:success n19/approval=approval:approved n20/delay=delay:success n21/task=task#7:success final: success (run 4) $ AGENTS/tools/wf-stand/run.sh 6 --stop-after 8 --expect stopped final: stopped (run 6) ``` Seeded workflows: "Exec happy" (task → approval → delay 5 s → task, ends `success` with `--approve`) and "Exec branches" (ok → fail; on_failure → recover, on_success → never started; always → 30 s slow task; ends `failed`). Templates are `bash` scripts from the local repo `/tmp/semaphore-stand/wf-repo` (`ok.sh`, `fail.sh`, `slow.sh`), so no network or Ansible is needed. `seed-outputs.sh` seeds the project "Artifacts QA" (project 1 since the 2026-10-07 rebuild) for testing workflow outputs by hand: 16 templates (bash producers for every rule of the contract — valid, empty, bad JSON, bad name, 101 outputs, 40 KB value, outputs-then-exit-1, symlink; bash and Ansible consumers with one survey var of every type; Terraform / Tofu with a `sensitive` and a hyphenated output; Ansible `set_stats`) and four workflows: 1 "producers -> consumers" (expect `success`, see `task.artifacts` of tasks of nodes 2–4), 2 "invalid producers" (expect `failed`, each bad producer `error` with the reason in its log, "empty" `success` without artifacts), 3 "failed producer" (expect `failed`, no artifacts stored, `on_failure` consumer ran), 4 "tofu -> consume" (expect `success`). Scripts: `/tmp/semaphore-stand/wf-repo/produce*.sh`, `consume.sh`, `tf/main.tf`, `playbooks/*.yml`. Ids land in `/tmp/semaphore-stand/wf-outputs-ids.txt`. Since 2026-10-08 the same seed adds the mapping checks: templates "bash: produce renamed outputs" and "ansible: set_stats renamed outputs" (output names `tag`, `count`, `flag`, `subnets`, `cfg`, `envname` that match no survey variable, so only an explicit edge mapping can deliver them) and workflows 9 "Inputs: explicit mapping" (renamed producers → bash and ansible consumers over `explicit` edges, `image_tag←tag`, `replicas←count`, …), 10 "Inputs: by_name through approval" (produce → approval → consumers, run with `--approve`), 11 "Inputs: fan-in by_name vs explicit" (produce by name and renamed explicitly into one consumer with convergence all: expect `image_tag` from the explicit edge, `replicas` by name), 12 "Inputs: explicit empty list" (the edge passes nothing). Consumers print one `INPUT name=value` line per survey variable (bash: parsed `k=v` args plus `env:env_name` — a `target: env` variable keeps its own name, it is not upper-cased; ansible: a debug list), so `inputs.sh <wf>` shows producer outputs next to what the consumer received. Expected since the resolver landed (2026-10-08): workflow 1 and 10 — the consumer's `INPUT` lines repeat the producer's `image_tag`, `replicas`, `enabled`, `subnet_ids`, `config` (by name; `env-name` with a hyphen is not delivered); workflow 9 — the renamed values (`image_tag=renamed-…`, `replicas=7`, `env:env_name=prod`); workflow 11 — `image_tag=renamed-…` from the explicit edge and `replicas=3` by name; workflow 12 — only `image_tag=static-from-node`, `replicas=1` (the default) and `env:env_name=static-env`; workflow 3 — the on_failure consumer is `error` before start with "Required input(s) without a value: image_tag" in its log. The task log of every consumer starts with the engine's `Input "<var>" <- output "<key>" of node N (task #M)` lines, so a value's source is always one line above the value. Since 2026-10-09 the seed also covers the Jinja rule (Ansible never evaluates an expression inside an extra var — every value reaches it through a file, the ones with a Jinja2 delimiter tagged `!unsafe`): template "bash: produce jinja outputs" (`produce_jinja.sh` writes `image_tag`, `config` and `replicas` holding `{{ lookup('pipe', …) }}`, `{{ lookup('env', 'HOME') }}`, `{{ 6*7 }}`), the variable group "vars group with jinja" (`group_expr: "{{ 2*21 }}"`), template "ansible: consume + vars group" and workflows 13 "Inputs: jinja injection" (→ ansible and bash consumers) and 14 "Inputs: jinja vs vars group". Expected on the server and on the runner: `INPUT image_tag={{ lookup('pipe', 'echo INJECTED-$(id -un)') }}`, `config` with the expressions verbatim, `replicas=1` (the default — `{{ 6*7 }}` is not an int) and `INPUT group_expr={{ 2*21 }}` — the variable group is data too. A consumer log containing `INJECTED-` or `group_expr=42` means Ansible evaluated a value: a regression. `inputs.sh` right after `run.sh` on the runner can miss the last log lines; re-run it with the run id. Trap: the template API ignores `environment_id`, pass `environment_ids`. Since 2026-10-10 the stand also checks the secret extra vars (TASK@CEA87DDD08): the survey secret `token` and the variable-group secret `db_password` (type `var`, added to "vars group with jinja" by hand through `PUT /project/1/environment/1` with `secrets:[{type:"var",name,secret,operation:"create"}]`) reach Ansible through a second, vault-encrypted `--extra-vars @task_<id>_secret_vars_*.yml` with a one-off `--vault-id <guid>@prompt`. `playbooks/consume.yml` prints `INPUT token=…` and `INPUT db_password=…`; template 37 "ansible: consume + own vault" (access key "tpl vault", type login_password, vault `default`) runs `playbooks/consume_vault.yml`, which loads `playbooks/vaulted.yml` (encrypted by `ansible-vault` with that key's password) through `vars_files` and prints `INPUT vaulted_var=…`. Expected on the server and on the runner: `INPUT token=s3cr3t {{ 1+1 }}`, `INPUT db_password=p@ss {{ 7*6 }}` literally; `ps -axo args=` shows `--vault-id=<guid>@prompt` and two `--extra-vars @`, never a secret or the password; `grep -rl s3cr3t /tmp/semaphore-stand/tmp` (or `runner-tmp`) finds nothing while the task runs; no `task_*_vars_*` file is left after. With `SEMAPHORE_LOG_LEVEL=DEBUG SEMAPHORE_DEBUG_FILTER=extra_vars` exported before `stand.sh start` / `runner.sh start`, the server and runner logs show seven `context=extra_vars` lines per task (split, two files written, vault added, two files removed, password forgotten). Checked 2026-10-10: server task 162, runner task 164, own vault task 171, regression runs 39 (wf 13) and 40 (wf 14). Traps: a vault-encrypted file must not sit in `playbooks/group_vars/` — Ansible loads it for every playbook of the directory and a template without that vault fails with "Decryption failed"; `vars_files` of the repository are still templated (`{{ 3*3 }}` prints `9`) — only values Semaphore passes are `!unsafe`; `runner.sh start | tail` hangs because the runner inherits the pipe — redirect to a file instead; a PUT of a template without the `vaults` field deletes its vaults, which is why `runner.sh tag/untag` re-reads each template by id before the PUT. Docs screenshots (2026-10-11): `seed-docs.sh` seeds a separate project "Demo Stand" (the name the published editor screenshot already shows) with "Provision network" (bash, outputs `vpc_id`, `subnet_ids`), "Build image" (bash, outputs `image_tag`, `replicas` — the values quoted in the user guide), "Deploy to cluster" (ansible `playbooks/deploy.yml`, survey `image_tag`, `replicas`, `subnets`) and the workflow "Build and deploy": Provision → Build → Deploy by name plus Provision → Deploy explicit (`subnets ← subnet_ids`). Run it once (`PID=<p> run.sh <wf> --expect success`), then `shoot-docs.cjs` writes `workflow-inputs-explicit.png`, `workflow-inputs-by-name.png`, `workflow-run-outputs.png` and `task-outputs.png` (dialog clipped) to `/tmp/semaphore-stand/shots-docs`; convert with `cwebp -q 88` into `docs/static/assets/`. Traps: a workflow must have exactly one root node (the explicit edge alone would make Provision and Build two roots); key hints need a run of the current revision, so re-run after any re-seed; the editor fits a three-node graph at ~45 % on a 1440 px viewport — the script collapses the palette (`.WorkflowEditor__sideToggle`) and clicks the fit control after the side panel opens instead of zooming in, which pushes nodes under the panel. Seeding traps learned there: a Terraform-family template must be POSTed without `inventory_id` (the API creates a `terraform-workspace` inventory; a shared one gets claimed and hidden) and with `task_params.auto_approve`, or a plan with changes parks the task in `waiting_confirmation`; a workflow must have exactly one root node; `survey_vars[].default_value` is a plain string; a JSON `\"` inside `$( )` inside a double-quoted bash string is mangled — build such fragments in a variable first. Traps: `run.sh` exits 1 when `--expect` does not match or `--timeout` (default 180 s) passes; `--approve` resolves every pending approval it sees, so use `--run ID` to only follow an existing run. `stand.sh build` rebuilds the Vue app into `api/public` (a tracked-ignored embed input) and the binary at `/tmp/semaphore-stand-bin`; it needs the `pro_impl` workspace for Workflows to be enabled. The stand DB is `/tmp/semaphore-stand/database-wf.sqlite` and persists between sessions. `runner.sh` registers a global runner "wf-runner" (tag `wf`, local executor, `/tmp/semaphore-stand/runner-config.json`, log `runner.log`) and starts it from the same binary; `tag` sets `runner_tag` on every template of project `PID` (default 1) so their tasks go to it, `untag` sends them back to the server. The remote-runner check of workflow outputs (2026-10-08): `runner.sh start && runner.sh tag && run.sh 1 --expect success && run.sh 2 --expect failed`, then `sqlite3 /tmp/semaphore-stand/database-wf.sqlite "select id,status,runner_id,length(artifacts) from task order by id desc limit 13"` shows `runner_id` of the runner and `artifacts` on the producers only. Traps: the token is returned once at creation, so a runner whose config file is gone is deleted and recreated; stop the runner and `untag` before a session that expects tasks to run on the server, or they wait forever; `status` keeps saying `online` for up to 120 s after `stop` (the server's heartbeat timeout), trust the `process:` line. `seed-survey.sh` (2026-10-16, TASK@B197C72B7F) needs the templates of `seed-outputs.sh` and adds workflow "Survey: workflow variables": survey `env` (enum, default `staging`), `image_tag` (required), `replicas` (int, default 2); node 2 "bash: consume" bound `image_tag←image_tag`, `replicas←replicas`, `env_name←env` on top of static `image_tag=static-from-node`; node 3 the same template without bindings (must receive nothing although the names match); node 4 "bash: produce renamed outputs" → node 5 "bash: consume" over an explicit edge `replicas←count` plus the binding `image_tag←image_tag`. Start a run with a body: `POST …/workflows/<id>/runs {"environment":{"image_tag":"1.2.3","env":"prod"}}` (ids in `/tmp/semaphore-stand/wf-survey-ids.txt`). `shoot-editor.cjs` logs in, opens the editor, clicks the first card whose title matches, scrolls the first bound survey field into view and writes the page, a crop of the task params card (`<out>-fields.png`) and the open assign menu (`<out>-assign.png`). `shoot-run-dialog.cjs` opens the workflow page, presses Run, checks that an empty required answer is refused, fills `image_tag` (`IMAGE_TAG`, default 1.2.3) and the first enum option, starts the run and shoots `run-dialog-invalid.png`, `run-dialog.png` and `run-view-variables.png` in `out_dir`; it prints the run id and the Variables chips. ⚠️ 2026-10-16: macOS purges files (not directories) under `/tmp` that were not touched for ~3 days — `config-wf.json`, `database-wf.sqlite`, the admin user and every script in `wf-repo` vanished between sessions. `stand.sh build` + a fresh `config-wf.json` (sqlite at `$DIR/database-wf.sqlite`, port `:3100`, three `openssl rand -base64 32` keys, `use_remote_runner: true`), `migrate`, `user add --admin --login admin --password admin123` and the seeds bring it back; `wf-repo` scripts must be recreated before any run.  # mocks — approved mock, screenshots and the scripts that shoot them Design artefacts of the editor redesign (`TASK@88179c9bc1`); decisions are in `../editor-architecture.md`, not here. Every script targets the local stand `http://localhost:3100` (admin/admin123, project 1) and Playwright loaded through `NODE_PATH` with `channel: 'chrome'` — stand and Playwright recipes are in `AGENTS/memory/ui-stands.md`. ## Files | File | What it is | | --- | --- | | `2026-09-26-workflow-node-mock.html` | Approved static mock: editor canvas, run view, card states, empty state; `#dark` in the URL flips the theme. Open from the repo checkout — MDI icons load from `web/node_modules`. Its "Tab opens quick-add" hint is stale (see ⚠️ in `editor-architecture.md`). | | `2026-09-26-workflow-node-mock-{light,dark}.png` | Renders of the mock as approved. | | `workflow-editor/editor-{light,dark}.png`, `editor-selected-*.png`, `editor-quickadd-light.png`, `editor-legacy-*.png`, `editor-empty-light.png`, `run-{light,dark}.png` | Screenshots of the shipped UI at 1440 × 900 @2x, shot by `shoot-wf.cjs`. "Legacy" is a workflow saved without positions (auto layout). | | `workflow-editor/editor-interactions.png` | End state of the `interact-wf.cjs` checklist. | | `workflow-editor/run-approval-pending.png`, `run-delay-countdown.png` | Run view with a pending approval and the delay countdown, from `approve-wf.cjs`. | | `workflow-editor/editor-edge-explicit-{light,dark}.png`, `editor-edge-byname-{light,dark}.png`, `run-outputs-{light,dark}.png`, `task-outputs-{light,dark}.png` | Workflow inputs (2026-10-09, `TASK@1845d9d4d7` stage 7): the edge panel with "Map inputs explicitly" and the mapping table (keys suggested from the last run), the by_name panel with the destination's survey variables (a check on those the source produced), the run view with "N outputs" on producer cards and the swap icon on explicit pills, the task dialog's Outputs panel. Shot by `shoot-inputs.cjs` on the "Artifacts QA" project. | | `survey/editor-bindings.png`, `survey/editor-bindings-fields.png`, `survey/editor-bindings-assign.png`, `survey/editor-problem.png` | Workflow survey variables (2026-10-16, `TASK@B197C72B7F` stage 7, redesigned the same day on the owner's request): the editor with the survey in the left panel, "3 from workflow" on a bound card and the node panel whose bound survey fields are read-only with a link icon and an unbind cross; a crop of the task params card; the "assign a workflow variable" menu open next to an unbound field; the same workflow after the variable "Image tag" was deleted — "2 problems", Save disabled, badges on the bound nodes and the error under the orphaned field. Shot by `AGENTS/tools/wf-stand/shoot-editor.cjs` on workflow 11 of "Artifacts QA" (`seed-survey.sh`). | | `survey/run-dialog.png`, `survey/run-dialog-invalid.png`, `survey/run-view-variables.png` | Workflow survey at run time (2026-10-16, `TASK@B197C72B7F` stage 8): the "Run" dialog with the survey fields seeded from the defaults, the same dialog refusing an empty required answer, and the run view with the "Variables" strip (`run.environment`) under the toolbar. Shot by `AGENTS/tools/wf-stand/shoot-run-dialog.cjs` on workflow 11 of "Artifacts QA". | | `workflow-editor/editor-revision-active-run.png`, `run-after-edit.png` | Revisions (2026-09-27): the editor with the "rev. 3" and "1 active run" chips, and run #8 still rendered on its revision 1 after two later saves. Shot with `AGENTS/tools/wf-stand/shoot-run.cjs`. | ## Scripts | Script | Does | Needs | | --- | --- | --- | | `seed-wf.sh` | Seeds five templates (one with an XSS name), the "Release" workflow with positions, the position-less "Nightly checks" (with a `<script>` note), starts one Release run; writes ids to `/tmp/semaphore-stand/wf-ids.txt`. Idempotent for templates. | Running stand, repository 1 and inventory 1 in project 1. | | `shoot-wf.cjs` | Editor/run/legacy/empty screenshots in light and dark; output `OUT` (default `/tmp/semaphore-stand/shots-wf`), `RUN` selects the run id. | `wf-ids.txt`. | | `interact-wf.cjs` | 16 PASS/FAIL checks on the editor: quick-add from the port, palette click, drag connect, cycle guard, pill condition change, snap, Delete, undo/redo round trip, problem badge + disabled Save, leave guard. Exits 1 on any FAIL or page error. | `wf-ids.txt`. Mutates the Release workflow in the browser but does not save. | | `approve-wf.cjs` | Approve inside the card, delay countdown ticks, viewport survives polling, task log opens on click. | `/tmp/semaphore-stand/wf3.txt` with `<workflow id> <run id>` of a run waiting at an approval — seeded by hand, not by `seed-wf.sh`. | | `keys-wf.cjs` | Keyboard pan/zoom/fit/reset in the editor and the run view; asserts no effect while typing in the properties panel. | `wf-ids.txt`, run 2 of Release. | | `shoot-inputs.cjs` | Shoots the four inputs screenshots above and runs 7 PASS/FAIL checks (checkbox state, mapping rows, hint line, by_name chips with a matched output, output count on a card, Outputs panel in the task dialog). `--dark` for the dark theme; `WF` (default 9, explicit workflow), `WF_BYNAME` (default 1), `OUT` (default `/tmp/semaphore-stand/shots-inputs`). Edges are selected by a dispatched `mousedown` on the path — a real click lands on the condition pill. | `AGENTS/tools/wf-stand/seed-outputs.sh` seeded, a finished run of the current revision of both workflows (`run.sh 9`, `run.sh 1`) for the key hints. | | `interact-inputs.cjs` | 10 PASS/FAIL checks of the inputs round trip on workflow `WF` (default 12): select the explicit edge, not dirty before editing, type a key, dirty, explicit icon on the pill, Save → API shows the pair, uncheck → by_name chips, Save → fields gone, original graph restored by PUT. Exits 1 on any FAIL or page error. | Running stand with the seeded project; mutates workflow 12 and restores it. | | `shoot-nodes.cjs` | Crops one card per node kind (task hovered with the "+", approval, delay, note) with edge pills hidden and zoom 1; source of `docs/static/assets/workflow-node-*.webp`. | `WF` env = id of the "Docs node kinds" workflow on the stand (default 4). | | `make-hotkeys-svg.py <out.svg>` | Generates the keyboard cheat-sheet `docs/static/assets/workflow-hotkeys.svg`; edit `COLUMNS` and re-run when a shortcut changes. | Python 3 only. | </yakaai_skills></article></body></html>

AI Agent Protocol & Instructions

Explore Related Technologies & Topics