foldrun 1.1.2 → 1.3.0

package/LICENSE

@@ -1,202 +1,39 @@
+foldrun proprietary licence
 
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+Copyright (c) 2026 foldrun. All rights reserved.
 
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+This software, its source code and its documentation are the property of
+foldrun. They are licensed, not sold.
 
-   1. Definitions.
+You may install and run the foldrun packages published to npm (`foldrun`
+and `@foldrun/core`) to write, check, run and deploy your own agents,
+flows and workspaces, on your own machines and with the foldrun platform.
+That includes the copies installing and running need, for your own use:
+package caches and mirrors, CI and build machines, container images and
+backups.
 
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
+You may not, except where the law allows it despite this restriction:
+copy, modify, merge, publish, distribute, sublicense, rent or sell the
+software or any part of it; reverse engineer, decompile or disassemble it;
+or use it to build a product or service that competes with foldrun.
 
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
+What you write with the software (your agents, flows, knowledge and other
+files) is yours.
 
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
+Third-party components the software includes or installs (its npm
+dependencies) remain under their own licences.
 
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
+This licence ends automatically if you break its terms, and you must then
+stop using the software.
 
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
+Versions published before 17 October 2026 under the Apache License 2.0
+remain available under that licence for those versions only.
 
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. TO THE EXTENT THE
+LAW ALLOWS, IN NO EVENT SHALL FOLDRUN BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+ITS USE.
 
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2026 foldrun contributors
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+Questions: hello@foldrun.io

package/README.md

@@ -1,8 +1,6 @@
 # foldrun
 
-[![ci](https://github.com/foldrun-io/foldrun-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/foldrun-io/foldrun-cli/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/foldrun)](https://www.npmjs.com/package/foldrun)
-[![licence](https://img.shields.io/badge/licence-Apache--2.0-blue)](LICENSE)
 
 **Agents are just folders.** An agent is a folder with a markdown file in it. A flow is
 a numbered list naming agents. You write them, read them, diff them in a pull
@@ -234,6 +232,7 @@ foldrun invoke publish --wait
 In CI, set `FOLDRUN_URL` and `FOLDRUN_TOKEN` instead — the environment always
 wins over the credentials file, so a job never reads one from disk.
 
-## License
+## Licence
 
-Apache-2.0.
+Proprietary; see [LICENSE](LICENSE). Versions published before 17 October
+2026 were Apache-2.0 and stay so.

package/bin/foldrun.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// foldrun — the open-source CLI.
+// foldrun — the CLI.
 //
 // Local-first by design: every command here works on a plain folder with no
 // account, no server and no network beyond the model call itself. That is the
@@ -104,6 +104,8 @@ const HELP = `foldrun — agents are just folders
   foldrun agent ls          the agents deployed in a workspace: model, description (--to, --json) — flow ls the flows and how each fires
   foldrun check [dir]       validate every workspace here, and the shared library
   foldrun check --to <ws>   validate the DEPLOYED copy instead — fetched from the platform, checked here
+  foldrun check --security  only the security rules: hard-coded secrets, hidden text, agents that can leak, unpinned code — fails on a warning
+  foldrun check --rules     every rule check knows: id, level, what it guards against (--json)
   foldrun agent run <name>  run one agent once on the platform (--task "…", --to, --wait, --test)
   foldrun agent link <agent>  add to its team, in its frontmatter: --subagent <worker>, --consult <agent> or --can-ask (--description for a worker with none)
   foldrun agent unlink <agent>  take one away: --subagent <name>, --consult <name> or --can-ask
@@ -302,7 +304,7 @@ Options
   --clear                   secrets sites: unbind it
   --add <site>              agent network: add a site to its network: list (repeatable)
   --remove <site>           agent network: take a site off its network: list (repeatable)
-  --out <file>              api spec: where to write the OpenAPI document (default: stdout)
+  --out <file>              api spec: where to write the OpenAPI document (default: stdout); check: where to write the JSON or SARIF report
   --file <path>             source put, library put, flow paste: the local file to send (default: stdin); secrets set --kind file|service-account: the file it holds; storage get, report get, report live, account export, export, billing statement: where to write it (- for stdout)
   --message "<why>"         source put: recorded on the file's revision
   --account                 secrets: account scope instead of the workspace's
@@ -344,6 +346,11 @@ Platform options (deploy, invoke, secrets, logs, keys)
   --force                   deploy: deploy even while runs are in flight; pull, storage get: overwrite local files
   --yes                     deploy: allow deleting files this folder no longer has (asked otherwise; required with no terminal)
   --platform --yes          workspaces rm: delete it on the platform, deliberately
+  --format <text|json|sarif>  check: how to print the findings (--json is --format json; sarif is for GitHub code scanning); --out <file> writes it there
+  --fail-on <level>         check: exit 1 on a finding at this level or above — error (default), warn, info, never; --security makes it warn
+  --rule <id>               check: only this rule, or a category (secret, security, content, supply-chain, config); repeat or comma-separate
+  --changed                 check: only findings in files changed against git HEAD (--base <ref> compares with that ref instead, e.g. origin/main)
+  --write-baseline          check: accept every current finding into .foldrun/check-baseline.json, so later checks show only new ones (--no-baseline ignores it)
   --platform                workspaces new, agent new, flow new, tool new: make it on the platform, not in this folder
 
 Nothing here needs an account. Set ANTHROPIC_API_KEY to run; init and check
@@ -360,9 +367,9 @@ if (!command || command === "--help" || command === "-h") {
 // `--value` as the account's argument and stored an empty secret; `--force
 // ./dir` swallowed the directory. A flag followed by another flag is also
 // boolean, so an unlisted switch at least does not eat its neighbour.
-const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear"]);
+const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules"]);
 // Flags said more than once collect into a list: `--tag a --tag b`.
-const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove"]);
+const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule"]);
 // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
 // a span: `--wait 30m`, `--wait event`. Only a value that reads as one is
 // taken, so `invoke x --wait` and friends are as they were.

package/docs/api.md

@@ -68,6 +68,7 @@ api workspaces/$WS/flows/publish/run -X POST   # start a flow
 | `/api/workspaces` | GET, POST | list; create (`name`, plus one of: `template: true` — blank, just an AGENTS.md, what the dashboard sends; `starter: true` — the example researcher, writer and publish flow; `demo: true`; `files`). A POST to a name that exists deploys over it; add `ifAbsent: true` to create only — a name that exists is then `409` and nothing changes, decided atomically (the assistant's Create workspace and `foldrun assistant` send it) |
 | `/api/workspaces/<ws>` | GET, PATCH, DELETE | read; rename or re-describe (`name`, `description`), or set its defaults (`timezone`, `budget`, `notify` — null clears one, edited in AGENTS.md in place); delete |
 | `/api/workspaces/<ws>/vocabulary` | GET | which document kinds this workspace admits — its `docs` list is what `[[ ]]` resolves: knowledge, memory, `state/` and `storage/` files, plus the folders themselves |
+| `/api/workspaces/<ws>/check` | GET | what `foldrun check` says about the deployed copy, as findings with rule ids — what a deploy refuses or warns about, and the scanner's secret, hidden-text, agent-risk and supply-chain rules ([Checks](checks)). `?security=1` keeps the security rules, `?rule=<id or category>` (repeatable) one; `{ counts, findings: [{ rule, level, file, line, message, fingerprint }], rules }`. Read-only, no model call |
 
 ## Source — the files themselves
 

package/docs/checks.md

@@ -0,0 +1,314 @@
+# Checks
+
+`foldrun check` answers two questions about a workspace before anything
+runs: **will it run?** (a tool that exists, a step that names a real agent,
+an option the parser can read) and **is it safe to run?** (a key pasted into
+a prompt, a knowledge file carrying hidden instructions, an agent that reads
+the open web, holds a secret and can send it anywhere). It is offline, calls
+no model and costs nothing, so run it after every edit, the way you would run
+a typecheck, and in CI on every pull request.
+
+```sh
+foldrun check                      # everything, as text
+foldrun check --security           # only the security rules; fails on a warning
+foldrun check --changed            # only files changed against git HEAD
+foldrun check --format sarif --out check.sarif   # for GitHub code scanning
+foldrun check --rules              # every rule, its level, what it guards against
+```
+
+The same findings appear in three other places, from the same rules in
+`@foldrun/core`:
+
+- **The dashboard**: the workspace's **Checks** page lists every finding on
+  the deployed copy, grouped by rule, each linking to its file. The editor
+  shows a file's own findings above it.
+- **The API**: `GET /api/workspaces/<ws>/check` answers with the same
+  findings as JSON (`?security=1`, `?rule=`). See [api](api).
+- **A deploy**: what a deploy refuses is still refused. A credential written
+  into a file and hidden text are reported as deploy warnings: the deploy
+  goes ahead and says so.
+
+## Reading a finding
+
+```
+   warn  knowledge/setup.md:6  an Anthropic key (sk-a…a5) is written into the file — move it to the vault and write `${NAME}`  secret/hardcoded
+```
+
+The level, the file and line, what is wrong, and the **rule id** at the end.
+A secret is never printed whole: the first four characters and the last two
+are enough to find it, and too few to use it.
+
+| Level | Means | Fails `check` |
+|---|---|---|
+| `error` | it will not work, or a deploy refuses it | yes |
+| `warn` | it works, and something about it should change | with `--fail-on warn` or `--security` |
+| `info` | worth knowing; often a judgement call | with `--fail-on info` |
+
+Every rule added with the scanner is a warning for now, so a workspace that
+passed yesterday still passes. To fail a build on them, use `--security` (which
+fails on a warning) or `--fail-on warn`.
+
+## Options
+
+| Flag | Does |
+|---|---|
+| `--security` | only the categories `secret`, `security`, `content` and `supply-chain`; exits 1 on a warning |
+| `--rule <id>` | only this rule, or a whole category (`secret`, `config`, …); repeat it, or comma-separate |
+| `--fail-on <level>` | exit 1 on a finding at `error` (the default), `warn`, `info`, or `never` |
+| `--format text\|json\|sarif` | how to print it; `--json` is `--format json`. `--out <file>` writes it to a file |
+| `--changed` | only findings in files changed against git `HEAD`, tracked or new; `--base <ref>` compares with that ref (`--base origin/main` in CI) |
+| `--write-baseline` | accept every current finding into `.foldrun/check-baseline.json`; later checks show only new ones. `--no-baseline` ignores the file |
+| `--rules` | list every rule (`--json` for the table) |
+| `--to <ws>` | check the copy deployed on the platform instead of this folder |
+
+## Ignoring one
+
+Put a comment on the line before the finding, or on the same line, naming
+the rule and saying why:
+
+```markdown
+<!-- foldrun-ignore secret/hardcoded: a revoked key, kept to show the format -->
+```
+
+```sh
+# foldrun-ignore supply-chain/pipe-to-shell: the vendor's pinned installer, checksum verified below
+```
+
+`foldrun-ignore-file <rule>: <reason>` anywhere in a file covers all of it.
+A category (`secret`) covers its rules. **The reason is required**: an ignore
+without one ignores nothing and is reported itself
+(`check/ignore-needs-reason`), because "why is this allowed?" is the question
+the next reviewer will ask. The same comments work for every rule, check's
+own included, in the CLI, the dashboard and the API.
+
+Ignores in `memory/` are not honoured. Agents write their memory
+themselves, so an ignore there could have been written by whatever an agent
+read: an injection that silences its own finding.
+
+## Adopting it on an existing workspace
+
+A workspace with years of history will have findings on day one. Do not fix
+them all before the check can be useful:
+
+```sh
+foldrun check --write-baseline     # accept what is there today
+git add .foldrun/check-baseline.json && git commit -m "check: baseline"
+foldrun check --security           # from now on, only new findings fail
+```
+
+A baseline entry is matched by the rule, the file and the text of the
+flagged line, not by its line number, so adding a paragraph above an
+accepted finding does not bring it back. Changing the flagged line does,
+because then it is a different line. A baseline that is not valid JSON
+hides nothing. `.foldrun/` is never deployed.
+
+## In CI
+
+```yaml
+# .github/workflows/check.yml
+on: [pull_request]
+permissions: { contents: read, security-events: write }
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm i -g foldrun
+      - run: foldrun check --format sarif --out check.sarif --fail-on never
+      - uses: github/codeql-action/upload-sarif@v3
+        with: { sarif_file: check.sarif }
+      - run: foldrun check --security --changed --base origin/${{ github.base_ref }}
+```
+
+The SARIF upload puts each finding on the line it is about, in the pull
+request. The last step fails the build on a new security finding in the
+files the pull request touched. Each result carries a stable fingerprint,
+so code scanning tracks a finding across commits instead of opening a new
+one every time.
+
+As a pre-commit hook: `foldrun check --security --changed`.
+
+## The rules
+
+The OWASP ids are from the
+[OWASP Top 10 for Agentic Applications (2026)](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026).
+
+### secret/hardcoded
+
+*warn · ASI03.* A credential is written into a file: an Anthropic, OpenAI,
+AWS, GitHub, GitLab, Slack, Google, Stripe, SendGrid, Twilio, Telegram, npm,
+Hugging Face, Linear, DigitalOcean, Shopify or Resend key, a JSON web token,
+a private key, a webhook URL that carries its own secret, a password inside a
+URL, or a field named like a credential (`api_key:`, `token:`, `password=`)
+holding a literal value that looks random. Everything in a workspace is
+deployed, versioned, readable by every agent and shown to the model.
+
+Move it to the vault (`foldrun secrets set NAME`), write `${NAME}` where it
+was, and bind it to the sites it is for (`foldrun secrets sites NAME
+api.example.com`) so it never enters a sandbox at all. Then **rotate the
+key**: it has already been copied, into git history if nowhere else.
+References (`${NAME}`, `$NAME`, `process.env.X`), names, and obvious samples
+(`your-key-here`, `xxxx`, AWS's `…EXAMPLE`) are not findings.
+
+### content/hidden-unicode
+
+*warn · ASI01, ASI04, ASI06.* Zero-width characters, bidirectional overrides
+or Unicode tag characters: invisible to a person reading the file, read as
+text by the model, and the standard way to hide an instruction from a
+reviewer. Tag characters are decoded in the message so you can read what
+they say. Delete them. A byte-order mark at the very start of a file is
+allowed.
+
+### content/injection-phrase
+
+*warn · ASI01, ASI06.* A line in knowledge, memory, a skill or a tool's
+description that reads as an order to the agent: "ignore previous
+instructions", "you are no longer…", "new instructions:", a fake `<system>`
+tag, "do not tell the user", "send the secrets to…". Agents read those files
+as material, and a line like that is either an attack that arrived with the
+content or a paste that will confuse the model. Remove it, or quote it as an
+example inside a fenced code block, where it is not flagged. An agent's own
+prompt is not checked, since a guard agent may need to talk about exactly
+this.
+
+### content/encoded-blob
+
+*info · ASI01, ASI04.* Three hundred or more characters of base64 in a
+markdown file. A reviewer cannot read it and the model can. Move data to a
+file and link it. An inline image (`data:image/…;base64,`) says what it is
+and is not flagged.
+
+### security/lethal-trifecta
+
+*warn · ASI01, ASI02, ASI03.* One agent that **reads untrusted content** (the
+`web` tool, or a browse/fetch/scrape tool), **holds something private** (a
+secret, an `apis:` entry, an MCP server) and **has a way out** (an open
+network, which is the default for an agent that reads the web, a tool marked
+`outward: true`, or an API it may POST, PUT, PATCH or DELETE to). Any page it
+reads can tell it to send what it holds anywhere it can reach.
+
+Take a leg away:
+- take it off the open network: `network: { level: trusted, allow:
+  [api.example.com] }`, or `network: trusted` ([Network](network)). A bare
+  list of sites only adds to a level, so an agent that reads the web stays
+  `open` with one. The level is resolved the way a run resolves it: the
+  agent's, then the workspace's `AGENTS.md`, then the account's;
+- split it into a reader with no secrets and a sender that reads nothing
+  untrusted;
+- guard its calls with a `hooks:` gate ([Hooks](hooks)).
+
+`permissionMode: plan` also clears it. An approval (`!`) on each outward step
+is the other answer, though this rule looks at the agent, not the flow.
+
+### security/subagent-wider
+
+*info · ASI03.* A sub-agent declares tools its parent does not have. A
+sub-agent never gets more than its parent, so they are dropped inside the
+delegation. Grant them to the parent, or remove them from the sub-agent.
+
+### flow/outward-ungated
+
+*the step's level · ASI02, ASI09.* A step whose agent holds an `outward:
+true` tool, with no `verify:` and no approval. Give it a `verify:` that reads
+what it did, or a `!`, so a wrong post or send is caught before it happens
+again. An error in `foldrun check`, a warning at deploy.
+
+### supply-chain/pipe-to-shell
+
+*warn · ASI04, ASI05.* `curl … | sh` (or `wget`, `bash`, `zsh`) runs whatever
+the server returns today, unreviewed, in the sandbox that holds the
+workspace. Declare the package under `runtime: system:` or `packages:`, or
+download it, verify a checksum, then run it.
+
+### supply-chain/unpinned-mcp
+
+*warn · ASI04.* An MCP server started with `npx`, `bunx`, `pnpx` or `uvx`
+with no version, or at `@latest`. Every run installs whatever was published
+last, so a compromised release reaches you the moment it ships. Pin it:
+`npx -y some-server@1.4.2`.
+
+### supply-chain/unpinned-package
+
+*info · ASI04.* A `runtime: packages:` or `npm:` entry with no version. Pin a
+range (`pandas>=2,<3`, `lodash@^4`) so tomorrow's run uses what was tested
+today.
+
+### config/unknown-field
+
+*warn or info.* A frontmatter key that this kind of file does not read. There
+are three cases, each with its own message:
+- **A near-miss** of a real field (`tolls:`, `triger:`, `disallowed_tools:`) is
+  a warning that names the field it meant. YAML accepts a typo, so it is
+  silently ignored, and `tolls: [web]` leaves the agent with no tools.
+- **A field read somewhere else** is a warning that says where it goes.
+  `timeout: 3600` on an agent is a step option, so it belongs under the step
+  in the flow. `language:` on a flow is read from the agent or `AGENTS.md`.
+- **A field like nothing foldrun reads** (`favourite_colour:`) is a note,
+  since another tool may own it.
+
+### config/wrong-type
+
+*warn.* The right field holding the wrong kind of value: a map where a list
+of names goes (`tools: {web: true}`), a list where one word goes. The runtime
+does not read it. The message says what the field takes.
+
+### config/invalid-value
+
+*warn.* A value that does nothing, or quietly does something else:
+- `effort: extreme` runs at the model's default;
+- `size: giant` becomes `large`;
+- `permissionMode:` other than `plan` is ignored;
+- `trigger: sometimes` never fires;
+- a `schedule:` the scheduler cannot read (`every day`) never fires. This is
+  checked with the scheduler's own cron parser;
+- an unknown HTTP method in `methods:` is dropped;
+- a duration that is not one (`debounce: soon`).
+
+Aliases count as valid: `effort: quick` is `low`. Fields another rule already
+checks in depth (`network:`, `limits:`, `timezone:`, `web:`) are left to it,
+so nothing is reported twice.
+
+### config/missing-field
+
+*warn.* A required field is absent: a skill with no `description:` is never
+loaded, because the model chooses skills by their descriptions.
+
+Every field these four rules know is listed, with its type and values, in one
+place in `@foldrun/core` (`frontmatter-fields.ts`). The editor's completions
+come from the same list, so what the editor suggests and what `check`
+accepts cannot drift apart.
+
+### check/ignore-needs-reason
+
+*warn.* A `foldrun-ignore` with no reason after a colon. It ignores nothing
+until it has one.
+
+### check's own rules
+
+These are what `check` has always reported, now with ids so they can be
+filtered, ignored and baselined. Each problem keeps its own level.
+
+| Rule | Covers |
+|---|---|
+| `agent/config` | frontmatter that cannot be read; a tool, skill, colleague, sub-agent or hook that does not exist; retired tool names |
+| `flow/config` | a step naming nothing, an option the parser cannot read, `verify:` written as prose, an arrangement that cannot have what its instruction asks for |
+| `tool/config` | a `run:` program that is missing, an import nothing declares, a leftover `type:` |
+| `skill/config` | a `SKILL.md` without a usable name or description |
+| `eval/config` | an eval that names nothing, or has no cases |
+| `hook/config` | a hook folder that is not a valid hook; a `hooks:` name that resolves to nothing |
+| `knowledge/okf` | a knowledge or memory document that is not a conformant bundle entry, an unreadable date, a stale document |
+| `workspace/config` | an `AGENTS.md` setting that cannot be read; a path a deploy refuses |
+| `library/config` | the same, in the account's shared library |
+| `paths/workspace-spelling` | `../../storage/x` where `workspace/storage/x` reads the same everywhere |
+
+## What it does not do
+
+It reads files; it does not run them. Static rules catch what the files
+say, not what a model will do with a page it has not read yet, so they are
+the first line, not the only one: [network](network) policy, bound
+[secrets](secrets), [hooks](hooks) and approvals hold at run time whatever
+the files say. MCP servers are never started to inspect their tools, and no
+URL is fetched.

package/docs/cli.md

@@ -39,7 +39,8 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun agent ls` | the agents deployed in a workspace — name, model, description (`GET …/agents`); `flow ls` the flows and how each fires (`GET …/flows`). `--to <workspace>`, `--json` for the list as the platform returns it |
 | `foldrun guide` | the coding-agent rules, copied from what Next.js does: a short managed block in the account's `AGENTS.md`, between `<!-- BEGIN:foldrun-agent-rules -->` markers, telling a coding agent (Claude Code, Cursor, Codex) to read `foldrun docs` before it writes an agent, flow or tool, and a `CLAUDE.md` that imports it with `@AGENTS.md`. `foldrun init` writes them, `foldrun pull` refreshes them, and `foldrun check` re-adds them when a coding agent runs it and they are missing or old — as `next dev` does. Only the block is rewritten, in place; text around it is kept. The runtime strips the block, so the agents that run in the account never see it; the rest of `AGENTS.md` stays their shared context. `--check` exits 1 when the block is missing or old (for CI), `--print` writes it to stdout |
 | `foldrun docs [page]` | these docs, from the copy that ships inside the CLI — the way Next.js ships `node_modules/next/dist/docs` — so a coding agent reads the version it is driving, offline. No page lists them; `foldrun docs flows` prints one; `--path` prints the folder. Design records and the platform operator's routes are left out |
-| `foldrun check [dir]` | validate agents, flows, tools, evals, knowledge — offline. At an account root: every workspace, then the shared library. Includes each agent's colleagues: an `agents:` or `subagents:` name that is not an agent, a sub-agent with no `description:`, a sub-agent that would hold none of its tools inside its parent's. Signed in, it also asks the platform's open `/api/version` which Chrome its runner image has, and warns when a pinned `web.browse.user_agent:` claims another major ([why](tools#how-this-agents-browser-presents-itself)); it warns about the old `web.browse.session:` key too (now `vendor_session:`). Hooks: a `hooks/<name>/` folder that is not a valid hook (`on:`, `run.mjs` beside `hook.md`, `tool:` only on tool events, `timeout:` 1 to 120), and a `hooks:` name in an agent or an AGENTS.md that is in neither `hooks/` nor the library, are errors; a `tool.call` hook on an agent whose `web.search:` (or `web.fetch:`) the model provider runs on its own servers is a warning — those calls never reach the hook |
+| `foldrun check [dir]` | validate agents, flows, tools, evals, knowledge — offline. At an account root: every workspace, then the shared library. Includes each agent's colleagues: an `agents:` or `subagents:` name that is not an agent, a sub-agent with no `description:`, a sub-agent that would hold none of its tools inside its parent's. Signed in, it also asks the platform's open `/api/version` which Chrome its runner image has, and warns when a pinned `web.browse.user_agent:` claims another major ([why](tools#how-this-agents-browser-presents-itself)); it warns about the old `web.browse.session:` key too (now `vendor_session:`). Hooks: a `hooks/<name>/` folder that is not a valid hook (`on:`, `run.mjs` beside `hook.md`, `tool:` only on tool events, `timeout:` 1 to 120), and a `hooks:` name in an agent or an AGENTS.md that is in neither `hooks/` nor the library, are errors; a `tool.call` hook on an agent whose `web.search:` (or `web.fetch:`) the model provider runs on its own servers is a warning — those calls never reach the hook. It is also the security scanner: a credential written into any file, invisible Unicode, override phrases in knowledge and skills, an agent that reads the web while holding a secret and an open way out, `curl \| sh`, an MCP server at no fixed version, a typo of a frontmatter field. Every finding names its rule (`secret/hardcoded`, `agent/config`, …); see [Checks](checks) |
+| `foldrun check --security` | only the security rules (secret, security, content, supply-chain), exiting 1 on a warning. Also `--rule <id or category>` (repeatable), `--fail-on error\|warn\|info\|never`, `--format text\|json\|sarif` (`--json`; `--out <file>`), `--changed` (only files changed against git HEAD; `--base <ref>`), `--write-baseline` (accept today's findings into `.foldrun/check-baseline.json`; `--no-baseline`), `--rules` (list every rule). A `foldrun-ignore <rule>: <reason>` comment on the line before a finding silences it; the reason is required. [Checks](checks) |
 | `foldrun extract [dir]` | move each single-file script tool — a `tools/<name>.md` with its program in a fenced block — into a folder: `tools/<name>/tool.md` with `run:` pointing at `run.js`, `run.py` or `run.sh` beside it. Frontmatter is edited as text, never re-serialised, so the diff is only what moved. A tool that already has a folder is left for you; `--dry-run` lists what it would do |
 | `foldrun check --to <ws>` | validate the copy that is DEPLOYED, rather than the folder in front of you — a workspace edited through the API, by an agent or by `foldrun source put`, has had no way to be checked short of spending a run. The files are fetched into a temporary folder and the ordinary check runs over them, so there is one copy of the rules; the output names the workspace and the platform it checked |
 | `foldrun agent run <name>` | run one agent once on a platform, with no flow file: a flow of one step. `--task "…"` is the instruction and is required. Prints the run id and how to follow it; `--wait` holds on (in 25-second pieces, as `invoke` does) and then prints the same report `foldrun report` would; `--test` makes it a [test run](runs#test-runs) |

package/docs/faq.md

@@ -52,5 +52,5 @@ file store. Nothing is hidden in a database only the platform can read, and
 a deploy never touches what an agent learned or a run recorded.
 
 **Can I run it on my own hardware?** The CLI and runtime, yes — that is
-what they are for, and they are open source. The platform itself is hosted
+what they are for, and they are free. The platform itself is hosted
 only. See [Running it yourself](self-hosting).

package/docs/introduction.md

@@ -36,7 +36,7 @@ The design bets on three things:
 
 The same workspace moves between them with `foldrun deploy` or a `git push`.
 Start locally; that is where every workspace should be born. The CLI and
-runtime are open source (Apache-2.0); the platform is not distributed — see
+runtime are free from npm; the platform is not distributed — see
 [Running it yourself](self-hosting).
 
 ## Where to go

package/docs/self-hosting.md

@@ -5,11 +5,12 @@ them unchanged.
 
 | shape | for | what is yours |
 |---|---|---|
-| **your machine** | one person, no server — the open-source CLI and runtime | everything: the files, the runs, the model bill |
+| **your machine** | one person, no server — the foldrun CLI and runtime, free from npm | everything: the files, the runs, the model bill |
 | **the hosted platform** | a team; schedules, sandboxes, gates, a vault, a dashboard | your workspaces and their records; we run the machines |
 
-The framework — the format, the runner, the checks, the CLI — is Apache-2.0
-on [GitHub](https://github.com/foldrun-io) and npm. The platform that runs it
+The framework — the format, the runner, the checks, the CLI — is free to
+install from npm (`foldrun`, `@foldrun/core`) and use under foldrun's
+licence, which ships in each package. The platform that runs it
 for other people (the queue and its worker, per-step sandboxes on a cluster,
 metering, tenancy) is ours and is not distributed: there is no self-hosted
 platform. If you need it inside your own network, that is a conversation —

package/docs/tools.md

@@ -1787,6 +1787,13 @@ Run `scripts/pace.py --spent <amount> --budget <amount>` from this skill's
 folder, then report the verdict in one sentence.
 ```
 
+| field | |
+|---|---|
+| `name` | defaults to the folder's name |
+| `description` | **required**: what it does and when to use it. A skill without one is never loaded, because the model chooses skills by their descriptions |
+| `when` | run tags: the skill is loaded only on runs carrying one of them |
+| `license`, `compatibility`, `metadata`, `allowed-tools` | the Agent Skills format's optional fields. Accepted and carried, not read by foldrun |
+
 Only names and descriptions sit in context; the agent reads the full file when
 a task matches. So an agent can carry many skills for a few tokens each — which
 is the reason to move a procedure out of `agent.md` in the first place.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "foldrun",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
-  "license": "Apache-2.0",
+  "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
     "foldrun": "bin/foldrun.mjs"
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^1.1.0"
+    "@foldrun/core": "^1.4.0"
   },
   "files": [
     "bin",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
-    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts",
+    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts",
     "release": "node scripts/release.mjs",
     "typecheck": "tsc -p tsconfig.json",
     "docs:sync": "node scripts/sync-docs.mjs",
@@ -33,9 +33,6 @@
     "url": "git+https://github.com/foldrun-io/foldrun-cli.git"
   },
   "homepage": "https://foldrun.io",
-  "bugs": {
-    "url": "https://github.com/foldrun-io/foldrun-cli/issues"
-  },
   "keywords": [
     "agents",
     "llm",

package/src/commands.mjs

@@ -758,54 +758,355 @@ async function platformBrowsers(url) {
  */
 async function checkAccount(layout, flags) {
   const { readLibraryTree, LIBRARY_KINDS } = await core();
-  let worst = 0;
+  const opts = checkOptions(flags);
+  const text = opts.format === "text";
   if (!layout.workspaces.length) {
     console.log(`\n  ${c.amber("!")} no workspaces in ${layout.accountRoot} — \`foldrun new <name>\` makes one\n`);
     return 1;
   }
+  const all = [];
+  let baselined = 0;
   for (const name of layout.workspaces) {
     const dir = path.join(layout.workspacesDir, name);
     process.env.FOLDRUN_WORKSPACE = dir;
-    console.log(`\n  ${c.bold(name)}  ${c.dim(path.relative(layout.accountRoot, dir))}`);
-    worst = Math.max(worst, (await check(dir, flags)) ?? 0);
+    const r = await checkWorkspace(dir, flags, opts);
+    baselined += r.baselined;
+    if (text) {
+      console.log(`\n  ${c.bold(name)}  ${c.dim(path.relative(layout.accountRoot, dir))}`);
+      printCheck(r, opts);
+    }
+    const prefix = path.relative(layout.accountRoot, dir).split(path.sep).join("/");
+    // A library finding is the account's, reported once however many
+    // workspaces resolve that tool.
+    for (const f of r.findings) {
+      if (!f.account) all.push({ ...f, file: `${prefix}/${f.file}`, where: `${prefix}/${f.where}` });
+      else if (!all.some((x) => x.account && x.rule === f.rule && x.file === f.file && x.line === f.line && x.fingerprint === f.fingerprint)) all.push(f);
+    }
   }
 
   // The library, once — it is one thing however many workspaces read it.
   const files = readLibraryTree(layout.accountRoot);
   const problems = [];
-  const note = (level, where, message) => problems.push({ level, where, message });
+  const note = (level, where, message) => problems.push({ level, where, message, rule: checkRuleFor(`library/${where}`) });
   validateSkills(path.join(layout.accountRoot, "library"), note);
   const hc = await hooksCore();
   for (const p of hc ? hc.checkHooksDir(path.join(layout.accountRoot, "library", "hooks"), "account") : []) {
     const m = /^(hooks\/[^/:]+(?:\/hook\.md)?): (.*)$/s.exec(p);
     note("error", m ? m[1] : "hooks/", m ? m[2] : p);
   }
-  const counts = LIBRARY_KINDS.map((k) => ({ kind: k, n: files.filter((f) => f.kind === k).length })).filter((x) => x.n > 0);
-  console.log(`\n  ${c.bold("library")}  ${c.dim(counts.length ? counts.map((x) => `${x.n} ${x.kind}`).join(" · ") : "empty")}`);
-  for (const p of problems) {
-    console.log(`    ${p.level === "error" ? c.red("✗") : c.amber("!")} ${c.bold(`library/${p.where}`)}  ${p.message}`);
+  const scan = await scanCore();
+  const fp = scan?.findingFingerprint ?? localFingerprint;
+  let lib = problems.map((p) => toFinding({ ...p, where: `library/${p.where}` }, layout.accountRoot, fp));
+  if (scan?.filterIgnored) lib = scan.filterIgnored(lib, files.map((f) => ({ path: `library/${f.kind}/${f.path}`, content: f.content })));
+  if (scan) {
+    const outward = files.filter((f) => f.kind === "tools" && /^[^/]+(?:\/tool)?\.md$/.test(f.path) && /^outward:\s*true\s*$/m.test(f.content)).map((f) => f.path.replace(/(?:\/tool)?\.md$/, ""));
+    lib.push(...scan.scanFiles(files.map((f) => ({ path: `library/${f.kind}/${f.path}`, content: f.content })), { outwardTools: outward }).map((f) => ({ ...f, where: `${f.file}${f.line ? `:${f.line}` : ""}` })));
+  }
+  const libResult = narrowCheck(lib, layout.accountRoot, opts, "library");
+  baselined += libResult.baselined;
+  if (text) {
+    const counts = LIBRARY_KINDS.map((k) => ({ kind: k, n: files.filter((f) => f.kind === k).length })).filter((x) => x.n > 0);
+    console.log(`\n  ${c.bold("library")}  ${c.dim(counts.length ? counts.map((x) => `${x.n} ${x.kind}`).join(" · ") : "empty")}`);
+    for (const f of libResult.findings) {
+      console.log(`    ${f.level === "error" ? c.red("✗") : f.level === "warn" ? c.amber("!") : c.dim("·")} ${c.bold(f.where)}  ${f.message}  ${c.dim(f.rule)}`);
+    }
+    if (libResult.wrote) console.log(`    ${c.dim(`baseline: ${libResult.wrote}`)}`);
+    console.log();
   }
-  if (problems.some((p) => p.level === "error")) worst = 1;
-  console.log();
-  return worst;
+  all.push(...libResult.findings);
+  if (!text) emitCheck(all, opts, { root: layout.accountRoot, summary: `${layout.workspaces.length} workspaces and the library`, baselined });
+  return checkExit(all, opts);
 }
 
 async function check(workspace, flags = {}) {
-  const { problems, summary } = await checkProblems(workspace, flags);
-  const errors = problems.filter((p) => p.level === "error");
-  const warnings = problems.filter((p) => p.level === "warn");
+  const opts = checkOptions(flags);
+  const r = await checkWorkspace(workspace, flags, opts);
+  if (opts.format === "text") printCheck(r, opts);
+  else emitCheck(r.findings, opts, { root: workspace, summary: r.summary, baselined: r.baselined });
+  return checkExit(r.findings, opts);
+}
 
+function printCheck(r, opts) {
+  const errors = r.findings.filter((p) => p.level === "error");
+  const warnings = r.findings.filter((p) => p.level === "warn");
   console.log("");
-  for (const p of problems) {
+  for (const p of r.findings) {
     const tag = p.level === "error" ? c.red("error") : p.level === "warn" ? c.amber(" warn") : c.dim(" info");
-    console.log(`  ${tag}  ${c.bold(p.where)}  ${p.message}`);
-  }
+    console.log(`  ${tag}  ${c.bold(p.where)}  ${p.message}  ${c.dim(p.rule)}`);
+  }
+  const notes = [
+    ...(r.baselined ? [`${r.baselined} known in the baseline`] : []),
+    ...(opts.changed ? [`changed files only (vs ${opts.base})`] : []),
+    ...(opts.security ? ["security rules only"] : []),
+    ...(r.wrote ? [`baseline written: ${r.wrote}`] : []),
+    ...(r.noScanner ? ["this @foldrun/core has no scanner — `npm i -g foldrun@latest` for the security rules"] : []),
+  ];
+  const tail = notes.length ? `  ${c.dim(`(${notes.join("; ")})`)}` : "";
   console.log(
     errors.length === 0 && warnings.length === 0
-      ? `  ${c.green("✓")} ${summary} — no problems\n`
-      : `\n  ${summary} · ${errors.length} error${errors.length === 1 ? "" : "s"}, ${warnings.length} warning${warnings.length === 1 ? "" : "s"}\n`,
+      ? `  ${c.green("✓")} ${r.summary} — no problems${tail}\n`
+      : `\n  ${r.summary} · ${errors.length} error${errors.length === 1 ? "" : "s"}, ${warnings.length} warning${warnings.length === 1 ? "" : "s"}${tail}\n`,
   );
-  return errors.length ? 1 : 0;
+}
+
+// ---------------------------------------------------------------- check: rules, formats, baseline
+//
+// `check` is the linter and the scanner in one: its own rules (will this
+// run?) and core's scanner (is it safe to run? — secrets, hidden text, an
+// agent that can be talked into leaking, unpinned code). Every finding has a
+// rule id, a level, a file and a fingerprint, so the same result prints for
+// a person, as JSON for a script, or as SARIF for GitHub code scanning.
+
+/** Core's scanner, or null on a core from before it — check then runs its
+ *  own rules alone and says the security rules need a newer install. */
+async function scanCore() {
+  try {
+    scanRules = /** @type {any} */ (await import("@foldrun/core/scan"));
+    return scanRules;
+  } catch {
+    return null;
+  }
+}
+
+// The scanner module, once scanCore has loaded it — categoryOf and SARIF read it.
+let scanRules = null;
+
+const SECURITY_CATEGORIES = new Set(["secret", "security", "content", "supply-chain"]);
+const RANK = { error: 3, warn: 2, info: 1 };
+const FAIL_ON = { error: 3, warn: 2, info: 1, never: Infinity };
+
+/** The rule id of one of check's own problems, from where it was found —
+ *  core's ruleForWhere, so the deploy and the Checks page name the same
+ *  problem the same way. A core from before the scanner has no table, and
+ *  then this fallback reads the path the same way. */
+function checkRuleFor(where, kind) {
+  if (scanRules?.ruleForWhere) return scanRules.ruleForWhere(where, kind);
+  if (kind === "outward") return "flow/outward-ungated";
+  if (kind === "spelling") return "paths/workspace-spelling";
+  if (/(?:^|\/)(?:knowledge|memory)\//.test(where)) return "knowledge/okf";
+  const lib = where.startsWith("library/");
+  const top = where.replace(/^library\//, "").split(/[/:]/)[0];
+  const byTop = { agents: "agent/config", flows: "flow/config", tools: "tool/config", skills: "skill/config", ".agents": "skill/config", evals: "eval/config", hooks: "hook/config" };
+  if (byTop[top]) return byTop[top];
+  return lib || top === "library" ? "library/config" : "workspace/config";
+}
+
+function categoryOf(rule) {
+  return scanRules?.scanRule?.(rule)?.category ?? (rule === "flow/outward-ungated" ? "security" : "config");
+}
+
+function checkOptions(flags) {
+  const format = flags.json === true ? "json" : typeof flags.format === "string" ? flags.format : "text";
+  if (!["text", "json", "sarif"].includes(format)) throw new Error(`--format ${format} — use text, json or sarif`);
+  const security = flags.security === true;
+  const failOn = typeof flags["fail-on"] === "string" ? flags["fail-on"] : security ? "warn" : "error";
+  if (!(failOn in FAIL_ON)) throw new Error(`--fail-on ${failOn} — use error, warn, info or never`);
+  const rules = [].concat(flags.rule ?? []).flatMap((r) => String(r).split(",")).map((r) => r.trim()).filter(Boolean);
+  return {
+    format,
+    security,
+    failOn,
+    rules,
+    changed: flags.changed === true || typeof flags.base === "string",
+    base: typeof flags.base === "string" ? flags.base : "HEAD",
+    baseline: flags["no-baseline"] !== true,
+    writeBaseline: flags["write-baseline"] === true,
+    out: typeof flags.out === "string" ? flags.out : null,
+  };
+}
+
+/** sha256 over rule, file and text — core's findingFingerprint, for a core
+ *  without the scanner, so a baseline written by either matches. */
+function localFingerprint(rule, file, text) {
+  return crypto.createHash("sha256").update(`${rule}\0${file}\0${String(text).trim().replace(/\s+/g, " ")}`).digest("hex").slice(0, 16);
+}
+
+/** One of check's problems as a finding: a file (not a folder) and a line. */
+function toFinding(p, root, fp) {
+  const m = /^(.*?):(\d+)$/.exec(p.where);
+  let file = m ? m[1] : p.where;
+  const line = m ? Number(m[2]) : undefined;
+  if (/^agents\/[^/]+$/.test(file)) file += "/agent.md";
+  else if (/^(?:library\/)?tools\/[^/]+$/.test(file)) file = fs.existsSync(path.join(root, file, "tool.md")) ? `${file}/tool.md` : `${file}.md`;
+  const rule = p.rule ?? checkRuleFor(p.where);
+  return { rule, level: p.level, file, ...(line ? { line } : {}), message: p.message, fingerprint: fp(rule, file, p.message), where: p.where };
+}
+
+/**
+ * The file a finding is really in. readTree carries a single-file subagent
+ * (`.agents/agents/<name>.md`, `.claude/agents/<name>.md`) as
+ * `agents/<name>/agent.md`, so a finding on it names a file that is not
+ * there — and --changed, which asks git, would drop it. The content is the
+ * same, so the line still holds.
+ */
+function sourcePathOf(workspace, file) {
+  const m = /^agents\/([^/]+)\/agent\.md$/.exec(file);
+  if (!m || fs.existsSync(path.join(workspace, file))) return file;
+  // The same eligibility readTree uses: a regular file, never a link.
+  for (const alt of [`.agents/agents/${m[1]}.md`, `.claude/agents/${m[1]}.md`]) {
+    try {
+      if (fs.lstatSync(path.join(workspace, alt)).isFile()) return alt;
+    } catch {
+      // not there
+    }
+  }
+  return file;
+}
+
+/** Everything check finds in one workspace, narrowed by the flags. Findings
+ *  about the account library carry `account: true` and paths from the
+ *  account root, where they live — not from this workspace. */
+async function checkWorkspace(workspace, flags, opts) {
+  const { problems, summary, outwardTools } = await checkProblems(workspace, flags);
+  const scan = await scanCore();
+  const { libraryDir } = await core();
+  const accountRoot = path.dirname(libraryDir("default"));
+  const fp = scan?.findingFingerprint ?? localFingerprint;
+  /** @type {any[]} */
+  let findings = problems.map((p) => ({ ...toFinding(p, p.where.startsWith("library/") ? accountRoot : workspace, fp), account: p.where.startsWith("library/") }));
+  if (scan) {
+    const { readTree } = await core();
+    const files = readTree(workspace);
+    // One ignore syntax for every rule: check's own findings honour the
+    // same `foldrun-ignore <rule>: <reason>` comments the scanner does.
+    if (scan.filterIgnored) findings = [...scan.filterIgnored(findings.filter((f) => !f.account), files), ...findings.filter((f) => f.account)];
+    let accountNetwork;
+    try {
+      const md = path.join(accountRoot, "AGENTS.md");
+      if (md !== path.join(workspace, "AGENTS.md") && fs.existsSync(md)) accountNetwork = (await import("gray-matter")).default(fs.readFileSync(md, "utf8")).data?.network;
+    } catch {
+      // an unreadable account AGENTS.md is reported by its own check
+    }
+    for (const f of scan.scanFiles(files, { outwardTools, accountNetwork })) {
+      findings.push({ ...f, where: `${f.file}${f.line ? `:${f.line}` : ""}` });
+    }
+  }
+  findings = findings.map((f) => {
+    if (f.account) return f;
+    const file = sourcePathOf(workspace, f.file);
+    return file === f.file ? f : { ...f, file, where: `${file}${f.line ? `:${f.line}` : ""}` };
+  });
+  const r = narrowCheck(findings, workspace, opts, workspace, accountRoot);
+  return { ...r, summary, noScanner: !scan };
+}
+
+/** --rule / --security, then --changed, then the baseline (or writing one).
+ *  `accountRoot` is where findings marked `account: true` live. */
+function narrowCheck(findings, root, opts, label, accountRoot = root) {
+  let out = findings;
+  if (opts.rules.length) {
+    const want = new Set(opts.rules);
+    out = out.filter((f) => want.has(f.rule) || want.has(f.rule.split("/")[0]) || want.has(categoryOf(f.rule)));
+  }
+  if (opts.security) out = out.filter((f) => SECURITY_CATEGORIES.has(categoryOf(f.rule)));
+  // check's own skill rule already says a skill has no description, as an
+  // error; the schema's note would say it twice. Only when that error is
+  // still in the report — `--rule config/missing-field` keeps the note.
+  out = out.filter((f) => !(f.rule === "config/missing-field" && out.some((g) => g.file === f.file && g.rule === "skill/config" && /no description|needs name and description/.test(g.message))));
+  const file = path.join(root, ".foldrun", "check-baseline.json");
+  if (opts.writeBaseline) {
+    const created = new Date().toISOString();
+    const seen = new Map(out.map((f) => [`${f.rule}\0${f.file}\0${f.fingerprint}`, { rule: f.rule, file: f.file, fingerprint: f.fingerprint }]));
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ version: 1, created, findings: [...seen.values()].sort((a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule)) }, null, 2) + "\n");
+    return { findings: [], baselined: out.length, wrote: path.relative(process.cwd(), file) || file };
+  }
+  let baselined = 0;
+  if (opts.baseline && fs.existsSync(file)) {
+    let b = null;
+    try {
+      b = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+      // Unreadable hides nothing: failing open would hide every new finding.
+      out = [...out, { rule: "workspace/config", level: "warn", file: ".foldrun/check-baseline.json", message: "the baseline is not JSON — it hides nothing until it is rewritten (`foldrun check --write-baseline`)", fingerprint: "baseline", where: ".foldrun/check-baseline.json" }];
+    }
+    if (b?.version === 1 && Array.isArray(b.findings)) {
+      // An entry that is not {rule, file, fingerprint} hides nothing.
+      const entries = b.findings.filter((f) => f && typeof f === "object" && typeof f.rule === "string" && typeof f.file === "string" && typeof f.fingerprint === "string");
+      const known = new Set(entries.map((f) => `${f.rule}\0${f.file}\0${f.fingerprint}`));
+      const kept = out.filter((f) => !known.has(`${f.rule}\0${f.file}\0${f.fingerprint}`));
+      baselined = out.length - kept.length;
+      out = kept;
+    }
+  }
+  if (opts.changed) {
+    const here = changedFiles(root, opts.base, label);
+    // The account may not be the same repository, or have that ref: then
+    // nothing in the library counts as changed, and the workspace's own
+    // comparison still stands.
+    let there = here;
+    if (out.some((f) => f.account) && accountRoot !== root) {
+      try {
+        there = changedFiles(accountRoot, opts.base, "library");
+      } catch {
+        there = new Set();
+      }
+    }
+    out = out.filter((f) => {
+      const changed = f.account ? there : here;
+      return changed.has(f.file) || [...changed].some((c) => c.startsWith(`${f.file}/`));
+    });
+  }
+  return { findings: out, baselined };
+}
+
+/** Files changed against a ref, tracked or not, relative to `root`. */
+function changedFiles(root, base, label) {
+  const git = (args) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  try {
+    // -z: literal paths. Without it git quotes and escapes a name outside
+    // ASCII ("knowledge/\346\227\245.md"), which matches no finding.
+    const diff = git(["diff", "-z", "--name-only", "--relative", base]);
+    const untracked = git(["ls-files", "-z", "--others", "--exclude-standard"]);
+    return new Set([...diff.split("\0"), ...untracked.split("\0")].filter(Boolean));
+  } catch (err) {
+    const why = String(/** @type {any} */ (err).stderr ?? err).trim().split("\n")[0];
+    throw new Error(`--changed needs ${label === "library" ? "the account" : "this workspace"} in a git repository and a ref git knows (${base}) — ${why}`);
+  }
+}
+
+function checkExit(findings, opts) {
+  const bar = FAIL_ON[opts.failOn];
+  return findings.some((f) => RANK[f.level] >= bar) ? 1 : 0;
+}
+
+/** JSON or SARIF, to stdout or --out. */
+function emitCheck(findings, opts, { root, summary, baselined }) {
+  const clean = findings.map(({ where, account, ...f }) => f);
+  let body;
+  if (opts.format === "sarif") {
+    body = scanRules?.toSarif
+      ? scanRules.toSarif(clean, { version: CLI_VERSION })
+      : { version: "2.1.0", runs: [{ tool: { driver: { name: "foldrun check", version: CLI_VERSION, rules: [] } }, results: [] }], error: "this @foldrun/core has no scanner — update foldrun for SARIF" };
+  } else {
+    const counts = { error: 0, warn: 0, info: 0 };
+    for (const f of clean) counts[f.level]++;
+    body = { version: 1, tool: `foldrun ${CLI_VERSION}`, root, summary, counts, baselined, findings: clean };
+  }
+  const text = JSON.stringify(body, null, 2) + "\n";
+  if (opts.out) fs.writeFileSync(opts.out, text);
+  else process.stdout.write(text);
+}
+
+/** `foldrun check --rules`: every rule check knows, with its level and why. */
+async function checkRulesCmd(flags) {
+  const scan = await scanCore();
+  const rules = [
+    ...(scan?.SCAN_RULES ?? []).map((r) => ({ ...r, source: "scanner" })),
+    ...(scan?.CHECK_RULES ?? []).map((r) => ({ ...r, source: "check" })),
+  ];
+  if (flags.json === true || flags.format === "json") {
+    process.stdout.write(JSON.stringify({ rules }, null, 2) + "\n");
+    return 0;
+  }
+  console.log("");
+  for (const r of rules) {
+    const lvl = r.source === "check" ? c.dim("  var") : r.level === "warn" ? c.amber(" warn") : r.level === "error" ? c.red("error") : c.dim(" info");
+    console.log(`  ${lvl}  ${c.bold(r.id.padEnd(28))} ${r.title}${r.owasp?.length ? c.dim(`  ${r.owasp.join(" ")}`) : ""}`);
+  }
+  if (!scan) console.log(`\n  ${c.amber("!")} this @foldrun/core has no scanner — \`npm i -g foldrun@latest\` adds the secret, security, content and supply-chain rules`);
+  console.log(`\n  ${c.dim("var: check's own rules carry the level of each problem. Ignore one with a comment on the line before: foldrun-ignore <rule>: <reason>")}\n`);
+  return 0;
 }
 
 /**
@@ -823,10 +1124,12 @@ async function checkProblems(workspace, flags = {}) {
   const T = "default";
   const P = "workspace";
   const problems = [];
+  await scanCore(); // the rule table checkRuleFor reads
   // file:line, like every other linter — so an editor can jump to it and CI
-  // can annotate the right row.
-  const note = (level, where, message, line) =>
-    problems.push({ level, where: line ? `${where}:${line}` : where, message });
+  // can annotate the right row. Every problem carries a rule id, so --rule,
+  // a foldrun-ignore, a baseline and SARIF can all name it.
+  const note = (level, where, message, line, kind) =>
+    problems.push({ level, where: line ? `${where}:${line}` : where, message, rule: checkRuleFor(where, kind) });
 
   const agents = listAgents(T, P);
   const flows = listFlows(T, P);
@@ -1113,7 +1416,7 @@ async function checkProblems(workspace, flags = {}) {
     }
     // A spelling hint (../../storage → workspace/storage) is info, not a warning:
     // the old path works, and a check that cries wolf gets ignored.
-    for (const w of lintFlow(f, { agents: [...agentNames], outwardAgents })) note(w.level ?? (w.kind === "spelling" ? "info" : "warn"), `flows/${f.file}`, w.message, w.line);
+    for (const w of lintFlow(f, { agents: [...agentNames], outwardAgents })) note(w.level ?? (w.kind === "spelling" ? "info" : "warn"), `flows/${f.file}`, w.message, w.line, w.kind);
   }
 
   for (const e of evals) {
@@ -1176,7 +1479,10 @@ async function checkProblems(workspace, flags = {}) {
   }
 
   const summary = `${agentNames.size} agents · ${flows.length} flows · ${evals.length} evals · ${Object.keys(tools).length} tools`;
-  return { problems, summary };
+  // The scanner needs to know which tools act outside the workspace, across
+  // the library too — resolved here already, so it is handed over.
+  const outwardTools = Object.entries(usable).filter(([, d]) => /** @type {any} */ (d)?.outward === true).map(([n]) => n);
+  return { problems, summary, outwardTools };
 }
 
 /**
@@ -6267,11 +6573,14 @@ async function checkRemote(flags, layout) {
       fs.mkdirSync(path.dirname(abs), { recursive: true });
       fs.writeFileSync(abs, content);
     }
-    console.log(`\n  ${c.bold(ws)}  ${c.dim(`the deployed copy on ${url} · ${files.size} file${files.size === 1 ? "" : "s"}`)}`);
+    // JSON and SARIF own stdout; the framing goes to stderr then.
+    const say = checkOptions(flags).format === "text" ? console.log : console.error;
+    say(`\n  ${c.bold(ws)}  ${c.dim(`the deployed copy on ${url} · ${files.size} file${files.size === 1 ? "" : "s"}`)}`);
     process.env.FOLDRUN_WORKSPACE = dir;
     process.env.FOLDRUN_ACCOUNT = root;
-    const code = await check(dir, flags);
-    console.log(`  ${c.dim(`checked what is deployed, not this folder — ${ws} · ${url}`)}\n`);
+    // The baseline belongs to the folder it was written in, not to a temp copy.
+    const code = await check(dir, { ...flags, "no-baseline": true });
+    say(`  ${c.dim(`checked what is deployed, not this folder — ${ws} · ${url}`)}\n`);
     return code;
   } finally {
     if (before.workspace === undefined) delete process.env.FOLDRUN_WORKSPACE;
@@ -10048,8 +10357,11 @@ export async function run(command, positional, flags, workspace, layout) {
       // rules: write them, once, and say so — what `next dev` does.
       if (layout.kind !== "empty" && codingAgent() && !hasCurrentAgentRules(layout.accountRoot)) {
         const r = writeAgentFiles(layout.accountRoot);
-        console.log(`  ${c.dim(`coding-agent rules written for ${codingAgent()} — AGENTS.md ${r.agentsMd}, CLAUDE.md ${r.claudeMd}; read \`foldrun docs\` before editing`)}`);
+        // JSON and SARIF own stdout; a note there would break the parse.
+        const say = flags.json === true || (typeof flags.format === "string" && flags.format !== "text") ? console.error : console.log;
+        say(`  ${c.dim(`coding-agent rules written for ${codingAgent()} — AGENTS.md ${r.agentsMd}, CLAUDE.md ${r.claudeMd}; read \`foldrun docs\` before editing`)}`);
       }
+      if (flags.rules === true) return checkRulesCmd(flags);
       // --to names a workspace on a PLATFORM, so there is nothing local to
       // check and the folder this terminal stands in is beside the point.
       return typeof flags.to === "string"

package/src/guide.mjs

@@ -30,7 +30,7 @@ export function agentRulesBlock() {
 
 # Read foldrun's docs before you edit this folder
 
-This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value.
+This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value.
 
 This block is for coding tools. It is written and re-added by the foldrun CLI, and the runtime strips it, so the agents that run here never see it; the rest of this file is the account's own context, which they do read. Committing the block with your work keeps the tree clean.