@cirvix_ai/agent-control 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "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.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "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.
+
+      "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 [yyyy] [name of copyright owner]
+
+   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.

package/NOTICE

@@ -0,0 +1,42 @@
+Cirvix AgentControl — enforcement engine
+Copyright 2026 Umang Kumar, trading as Cirvix
+
+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.
+
+---
+
+WHAT THIS LICENCE COVERS
+
+This package is the enforcement engine: the policy evaluator, the risk
+classifier, the secret detector and handle substitution, the local control
+socket, the MCP gateway, the audit chain, the scanner, and the `cirvix` CLI.
+
+It is licensed under Apache 2.0 deliberately. A security control that cannot be
+read is a security control you are asked to take on faith, and this is the part
+that decides whether a tool call runs. Read it, fork it, audit it, run it in
+production without paying anything, and do not ask us for permission.
+
+WHAT IT DOES NOT COVER
+
+The Cirvix control plane — multi-tenant policy distribution, the team vault,
+SSO and SCIM, approvals workflow, hosted audit retention and export, compliance
+evidence reporting, fleet telemetry and billing — is a separate package under a
+separate, proprietary licence. See packages/control-plane/LICENSE.
+
+THIRD-PARTY CODE
+
+There is none. This package has zero runtime dependencies, deliberately and
+permanently — a security tool that drags in a transitive dependency tree is
+asking to become the supply-chain incident it exists to prevent.
+
+The self-hosted fonts shipped with the Cirvix website (Geist and Geist Mono) are
+licensed SIL OFL-1.1 and are not part of this package.

package/README.md

@@ -0,0 +1,341 @@
+# @cirvix_ai/agent-control
+
+Runtime governance for AI agents. Scan what is ungoverned, evaluate tool calls
+against policy, and keep a tamper-evident record of every decision.
+
+**Zero runtime dependencies.** A security tool that drags in a transitive
+dependency tree is asking to become the supply-chain incident it exists to
+prevent.
+
+## Install in 30 seconds
+
+No account, no signup, no config file, no daemon to leave running.
+
+```bash
+npx @cirvix_ai/agent-control scan
+```
+
+That reads your machine and tells you which agent runtimes are ungoverned. It
+writes nothing and sends nothing anywhere. Then decide one call:
+
+```bash
+npx @cirvix_ai/agent-control check --action fs.read --resource .env.production
+```
+
+```
+  DENY  fs.read .env.production
+  rule    deny-dotenv-read
+  reason  Reading .env files is denied outside an approved secrets flow. This is
+          the single most common path from a prompt injection to a live credential.
+  fix     Request the value as a handle: secrets.get("STRIPE_KEY")
+```
+
+To govern an agent rather than a single call, wrap its tools — the call cannot
+leave without being decided, so there is no verdict to forget to check:
+
+```bash
+npm install @cirvix_ai/agent-control
+```
+
+```js
+import { guard, CirvixDenied, STARTER_RULES } from "@cirvix_ai/agent-control";
+
+const tools = guard.wrap(myTools, { agent: "pr-triage", rules: STARTER_RULES });
+
+try {
+  await agent.invoke(input);
+} catch (err) {
+  if (err instanceof CirvixDenied) {
+    console.log(err.policy, err.remediation, err.decisionId);
+  }
+  throw err;
+}
+```
+
+Requires Node 20 or later. There is a second implementation of the same engine
+for Python — `pip install cirvix` — and the two are held to a shared
+conformance fixture that both must pass.
+
+**Full documentation:** [`docs/`](https://www.cirvix.com/docs.html) — [CLI reference](https://www.cirvix.com/docs.html), [Node SDK](https://www.cirvix.com/sdks.html), [policy reference](https://www.cirvix.com/policy-engine.html).
+
+## Licence
+
+Apache-2.0. The local enforcement engine is open source and ships with the
+Apache-2.0 licence and attribution notice in this package. The hosted Cirvix
+control plane is a separate product and is not included here.
+
+## `cirvix scan`
+
+Read-only inventory of this machine. No account, no network, nothing written.
+
+Finds the agent runtimes you have installed (Claude Code, Cursor, Windsurf,
+Cline, VS Code MCP), the frameworks declared in the current project, every MCP
+server configured across all of them, and the credential files an agent with
+filesystem access could read.
+
+```
+  runtimes            2 found
+    Claude Code       ~/.claude/settings.json
+                      ungoverned · 6 MCP servers
+    Cursor            ~/.cursor/mcp.json
+                      ungoverned · 4 MCP servers
+
+  mcp servers         7 configured
+    filesystem-mcp    stdio   broad scope
+    github-mcp        stdio   inline secrets · ×2 runtimes
+
+  credentials         3 paths reachable from agent context
+    AWS credentials   On disk and readable by any agent with filesystem access
+    .env.production   4 secret-shaped keys: STRIPE_KEY, DATABASE_URL…
+
+  findings            4 high · 3 medium · 1 low
+```
+
+**It never prints a secret value.** Key *names* only — reporting a leak by
+leaking it would be absurd.
+
+| Flag | Effect |
+|---|---|
+| `--json` | Machine-readable output |
+| `--deep` | Include MCP command lines |
+| `--fail-on <high\|medium\|low>` | Exit non-zero at that severity — for CI |
+| `--cwd <dir>` | Workspace root |
+
+## `cirvix check`
+
+Evaluate a single tool call against the policy set. Every decision names the
+rule that produced it.
+
+```bash
+$ cirvix check --action fs.read --resource .env.production
+
+  DENY  fs.read  /repo/.env.production
+  rule    deny-dotenv-read
+  reason  Reading .env files is denied outside an approved secrets flow.
+  fix     Request the value as a handle: secrets.get("STRIPE_KEY")
+```
+
+Exit code is `1` on deny, `0` otherwise — so it works as a gate in CI.
+
+## The policy engine
+
+An ordered rule set with three effects: `permit`, `forbid`, `hold`. Three
+properties are guaranteed and covered by tests:
+
+1. **`forbid` always wins.** No `permit` can override it, at any position.
+   This is what makes a rule set safe to extend — adding a permissive rule can
+   never silently punch a hole through an existing prohibition.
+2. **Default deny.** A request matching nothing is denied. Fail-open is how a
+   control plane becomes decorative the first time a rule file fails to parse.
+3. **Resources are canonicalized before matching.** `./x/../.env`, `.env`, and
+   the absolute path are one resource. Rules matching raw strings are bypassed
+   by the first traversal attempt.
+
+Conditions are **plain data, never expressions** — no `eval`, no
+`new Function`. A policy file is exactly the kind of thing that gets templated
+by a script, and making it an execution surface would turn the security
+product into the vulnerability.
+
+```json
+{
+  "name": "require-approval-prod-deploy",
+  "effect": "hold",
+  "actions": ["k8s.apply", "db.migrate"],
+  "resources": ["*"],
+  "when": [{ "path": "environment", "op": "in", "value": ["production"] }],
+  "approvers": ["platform-oncall"]
+}
+```
+
+Operators: `eq` `ne` `in` `nin` `gt` `gte` `lt` `lte` `matches` `exists`
+`contains` `supersetOf`. An unknown operator fails closed.
+
+## `guard.wrap()` — governing an agent that does not speak MCP
+
+The gateway governs everything, including tools added after you deployed it,
+because it sits on the wire. It also requires the agent to speak MCP. `wrap` is
+for when it does not — a LangChain executor, a crew, a hand-rolled loop over
+some functions:
+
+```js
+import { guard, CirvixDenied, CirvixHeld } from "@cirvix_ai/agent-control";
+
+const tools = guard.wrap(myTools, {
+  agent: "pr-triage",
+  environment: process.env.CIRVIX_ENV ?? "local",
+  rules,                     // or load them with loadPolicy({ policyDir })
+});
+
+try {
+  await agent.invoke(input);
+} catch (err) {
+  if (err instanceof CirvixDenied) {
+    console.log(err.policy);      // "deny-dotenv-read"
+    console.log(err.remediation); // 'secrets.get("STRIPE_KEY")'
+    console.log(err.decisionId);  // pass to `cirvix why`
+  }
+  throw err;
+}
+```
+
+**The trade, stated plainly.** You give up the property that makes the gateway
+worth deploying — it governs tools nobody told it about — because you are
+wrapping a list. You keep everything else: the same engine, the same rules, the
+same decision record, the same secret brokering, the same audit chain. That is
+not a slogan; `wrap` and the gateway call one `Guard`, so a rule cannot mean
+one thing here and another there.
+
+| It accepts | Example |
+|---|---|
+| An object of `name → function` | `{ read_file, run_query }` |
+| An array of tool objects carrying a callable | LangChain, CrewAI, AutoGen |
+| A single function | `guard.wrap(fn, { name: "read_file" })` |
+
+Tool objects come back with their descriptions, schemas, and framework
+metadata intact — and the array you passed in is left alone, so a framework
+holding the originals does not find them governed by surprise.
+
+**`CirvixDenied` vs `CirvixHeld`.** A denial means re-plan. A hold means this
+exact call may still happen once a person says yes, and carries `approvers`.
+They are separate types because collapsing them teaches an agent to treat both
+as failure.
+
+### Testing a policy like code
+
+```js
+import { evaluate, expectNoLoosening } from "@cirvix_ai/agent-control/testing";
+
+test("production writes are held for a human", async () => {
+  const decision = await evaluate({
+    policyDir: "./policies",
+    agent: "deploy-bot",
+    action: "k8s.apply",
+    resource: "production/checkout",
+    context: { environment: "production" },
+  });
+
+  expect(decision.verdict).toBe("hold");
+  expect(decision.approvers).toContain("platform-oncall");
+});
+```
+
+`expectNoLoosening({ before, after, calls })` is the pull-request counterpart:
+it reports any call the change would newly permit. Tightening passes — a
+security policy is allowed to move that way without surprising a reviewer.
+
+### Claude Code, Cursor, and other MCP clients
+
+Use the gateway, not `wrap`. They already speak MCP, and pointing them at
+`cirvix gateway` governs every server they load — including ones added later:
+
+```json
+{ "mcpServers": { "cirvix": { "command": "cirvix", "args": ["gateway", "--servers", "~/.cursor/mcp.json"] } } }
+```
+
+### Python
+
+```bash
+pip install cirvix
+```
+
+```python
+from cirvix import guard, CirvixDenied
+tools = guard.wrap(my_tools, agent="pr-triage", rules=rules)
+```
+
+Same API, native evaluator — not an HTTP client, because a round trip in the
+enforcement path would break the offline-first guarantee the daemon exists for.
+
+Which raises the obvious risk: two engines that can silently disagree are worse
+than one engine and an honest gap. What makes it safe is
+`packages/conformance/policy-conformance.json` — 44 cases both engines must
+answer identically, down to the canonical resource and the rule trace. Neither
+language gets a private copy. See `packages/cirvix-python`.
+
+## Secret handles
+
+An agent never receives secret material. It receives an opaque handle, and the
+real value is substituted into the outbound request at the gateway — after
+policy has authorized that specific destination.
+
+```js
+import { SecretsClient } from "@cirvix_ai/agent-control/secrets";
+
+const secrets = new SecretsClient({ apiUrl, apiKey, agent: "pr-triage" });
+
+const key = await secrets.get("STRIPE_RESTRICTED_KEY");
+// "sec_handle_a89f…" — this is everything the model ever sees.
+```
+
+Attach it to the gateway and the rest is automatic:
+
+```js
+const gw = new Gateway({ servers, rules, secrets });
+```
+
+| | |
+|---|---|
+| On the way out | Handles in a permitted call's arguments are resolved and substituted |
+| Off-path | A handle presented for an unsanctioned destination denies the call, rule `secret-broker` |
+| No destination | A call carrying a handle but naming no http(s) endpoint is refused |
+| Partially resolvable | If any handle fails, **nothing** is substituted — never a real credential beside a literal handle |
+| On the way back | Results are scanned for material this session resolved, and it is swapped back to its handle |
+
+**Substitution does not taint the session.** The `touchedSecret` flag that
+blocks egress after a raw credential read is deliberately not set here: an
+agent holding a handle never held the material, which is the entire point. The
+alternative would deny the second call to the very API the handle was for.
+
+**Leak detection covers material this session resolved, and nothing else.** A
+credential Cirvix was never told about cannot be recognised on the return
+path. This is a backstop, not a substitute for scoping what a handle reaches.
+
+## The audit chain
+
+Append-only JSONL where each record commits to the hash of its predecessor.
+
+```bash
+$ cirvix audit verify --file .cirvix/audit.jsonl
+
+  chain intact  43,675 records verified
+```
+
+Alter or delete any record and verification reports **where** it broke:
+
+```
+  chain broken  at record 2 of 3
+  Record 2 has been modified — its contents no longer match its hash.
+```
+
+**What this proves:** no record was altered or removed after it was written.
+**What it does not prove:** that a record was written truthfully in the first
+place — that comes from the enforcement path, not the log. It also does not
+prevent destruction; someone with disk access can delete the file. The chain
+guarantees doing so is *visible*.
+
+Hashes are SHA-256 over a canonical JSON serialization with sorted keys, so
+two semantically identical records hash identically.
+
+## Tests
+
+```bash
+npm test
+```
+
+93 tests covering the three policy invariants, traversal bypass attempts, glob
+safety under hostile patterns, condition safety, chain tamper detection,
+gateway interception against a real child-process MCP server, handle
+substitution on both the outbound and return paths, and the `guard.wrap`
+surface.
+
+## Status
+
+Pre-release. `scan`, `check`, `policy`, `why`, `replay`, `audit verify`,
+`gateway`, and `daemon` work today, as does secret brokering and `guard.wrap`
+when a control plane is configured. Not yet built: a Python SDK, and the
+hosted control plane — the one in `packages/control-plane` is self-hosted. See
+[cirvix.com](https://www.cirvix.com).
+
+## License
+
+See LICENSE. Cirvix is a product of Umang Kumar, trading as Cirvix.

package/action/README.md

@@ -0,0 +1,100 @@
+# `cirvix/scan`
+
+Find the AI agent runtimes, MCP servers, and reachable credentials in a
+repository that nothing is governing — on every pull request.
+
+```yaml
+- uses: cirvix/scan@v1
+```
+
+That is the whole minimum. It scans the checkout, writes a job summary,
+annotates blocking findings on the diff, uploads SARIF to code scanning, and
+fails the job on anything high.
+
+## First run on an existing repository
+
+Do not gate a merge on the first scan. Look at the baseline:
+
+```yaml
+- uses: cirvix/scan@v1
+  with:
+    fail-on: never
+```
+
+Then tighten once you know what is there.
+
+## A realistic workflow
+
+```yaml
+name: Agent governance
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # Required to put findings in the Security tab and on the diff.
+      security-events: write
+      # Only needed for comment-on-pr.
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cirvix/scan@v1
+        with:
+          fail-on: high
+          comment-on-pr: true
+```
+
+Without `security-events: write` the upload step is skipped rather than
+failing the job — the scan is still useful, the findings just stay in the
+summary.
+
+## Inputs
+
+| Input | Default | |
+|---|---|---|
+| `fail-on` | `high` | `high`, `medium`, `low`, or `never` |
+| `working-directory` | `.` | Directory to scan |
+| `sarif-file` | `cirvix-scan.sarif` | Empty string to skip SARIF |
+| `upload-sarif` | `true` | Send findings to code scanning |
+| `comment-on-pr` | `false` | One comment, edited in place on each push |
+| `version` | `latest` | Version of `@cirvix_ai/agent-control` to run |
+
+## Outputs
+
+`high`, `medium`, `low`, `passed`, and `findings` (the full JSON), so a
+workflow can branch without re-running the scan:
+
+```yaml
+- uses: cirvix/scan@v1
+  id: cirvix
+  with:
+    fail-on: never
+- if: steps.cirvix.outputs.high != '0'
+  run: echo "::notice::${{ steps.cirvix.outputs.high }} high findings"
+```
+
+## What it does not do
+
+- **It does not send your code anywhere.** The scan reads local configuration
+  files and reports what it finds. Nothing is uploaded except the SARIF you
+  asked GitHub to store.
+- **It does not execute anything.** No agent runs, no tool is called.
+- **It reports reachability, not wrongdoing.** "This runtime can read
+  `.env.production`" is not a claim that it did. That distinction is in the
+  summary text on purpose, because a security report that overstates gets
+  discounted entirely the first time somebody checks one.
+
+## Why a composite action
+
+There is no committed `dist/` bundle. A JavaScript action ships one, it has to
+be rebuilt on every change, and in practice it is the thing that goes stale.
+The CLI has zero runtime dependencies, so `npx @cirvix_ai/agent-control` is a
+smaller and more honest supply chain than a vendored bundle nobody re-reads.
+
+Pin `version` if you would rather not track `latest`.