@s-gw/s-gw 0.1.0

package/dist/windows/s-gw-credential.ps1

@@ -0,0 +1,167 @@
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true, Position = 0)]
+  [ValidateSet("get", "set", "delete", "status")]
+  [string]$Command,
+
+  [Parameter(Mandatory = $true)]
+  [string]$Service,
+
+  [Parameter(Mandatory = $true)]
+  [string]$Account,
+
+  [string]$Label = "s-gw local secret"
+)
+
+$ErrorActionPreference = "Stop"
+
+if (-not $IsWindows -and $PSVersionTable.PSEdition -eq "Core") {
+  throw "Windows Credential Manager is only available on Windows."
+}
+
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+
+public static class SgwCredMan {
+  public const UInt32 CRED_TYPE_GENERIC = 1;
+  public const UInt32 CRED_PERSIST_LOCAL_MACHINE = 2;
+
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  public struct CREDENTIAL {
+    public UInt32 Flags;
+    public UInt32 Type;
+    public string TargetName;
+    public string Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public UInt32 CredentialBlobSize;
+    public IntPtr CredentialBlob;
+    public UInt32 Persist;
+    public UInt32 AttributeCount;
+    public IntPtr Attributes;
+    public string TargetAlias;
+    public string UserName;
+  }
+
+  [DllImport("advapi32.dll", EntryPoint = "CredReadW", CharSet = CharSet.Unicode, SetLastError = true)]
+  public static extern bool CredRead(string target, UInt32 type, UInt32 flags, out IntPtr credentialPtr);
+
+  [DllImport("advapi32.dll", EntryPoint = "CredWriteW", CharSet = CharSet.Unicode, SetLastError = true)]
+  public static extern bool CredWrite(ref CREDENTIAL credential, UInt32 flags);
+
+  [DllImport("advapi32.dll", EntryPoint = "CredDeleteW", CharSet = CharSet.Unicode, SetLastError = true)]
+  public static extern bool CredDelete(string target, UInt32 type, UInt32 flags);
+
+  [DllImport("advapi32.dll", EntryPoint = "CredFree", SetLastError = true)]
+  public static extern void CredFree(IntPtr buffer);
+}
+"@
+
+function Get-TargetName {
+  return "s-gw/$Service/$Account"
+}
+
+function Get-LastErrorCode {
+  return [Runtime.InteropServices.Marshal]::GetLastWin32Error()
+}
+
+function Throw-Win32([string]$Action) {
+  $code = Get-LastErrorCode
+  $message = (New-Object ComponentModel.Win32Exception($code)).Message
+  throw "$Action failed ($code): $message"
+}
+
+function Read-CredentialValue([string]$Target) {
+  $ptr = [IntPtr]::Zero
+  if (-not [SgwCredMan]::CredRead($Target, [SgwCredMan]::CRED_TYPE_GENERIC, 0, [ref]$ptr)) {
+    $code = Get-LastErrorCode
+    if ($code -eq 1168) {
+      exit 44
+    }
+    Throw-Win32 "CredRead"
+  }
+
+  try {
+    $cred = [Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [type][SgwCredMan+CREDENTIAL])
+    $bytes = New-Object byte[] $cred.CredentialBlobSize
+    [Runtime.InteropServices.Marshal]::Copy($cred.CredentialBlob, $bytes, 0, $bytes.Length)
+    return [Text.Encoding]::Unicode.GetString($bytes).TrimEnd([char]0)
+  } finally {
+    [SgwCredMan]::CredFree($ptr)
+  }
+}
+
+function Test-CredentialValue([string]$Target) {
+  $ptr = [IntPtr]::Zero
+  if (-not [SgwCredMan]::CredRead($Target, [SgwCredMan]::CRED_TYPE_GENERIC, 0, [ref]$ptr)) {
+    return $false
+  }
+
+  [SgwCredMan]::CredFree($ptr)
+  return $true
+}
+
+function Write-CredentialValue([string]$Target, [string]$Value) {
+  if (-not $Value) {
+    throw "Cannot store an empty Credential Manager value."
+  }
+
+  $bytes = [Text.Encoding]::Unicode.GetBytes($Value)
+  $pinned = [Runtime.InteropServices.GCHandle]::Alloc($bytes, [Runtime.InteropServices.GCHandleType]::Pinned)
+
+  try {
+    $cred = New-Object "SgwCredMan+CREDENTIAL"
+    $cred.Type = [SgwCredMan]::CRED_TYPE_GENERIC
+    $cred.TargetName = $Target
+    $cred.Comment = $Label
+    $cred.CredentialBlobSize = [uint32]$bytes.Length
+    $cred.CredentialBlob = $pinned.AddrOfPinnedObject()
+    $cred.Persist = [SgwCredMan]::CRED_PERSIST_LOCAL_MACHINE
+    $cred.UserName = "$env:USERDOMAIN\$env:USERNAME"
+
+    if (-not [SgwCredMan]::CredWrite([ref]$cred, 0)) {
+      Throw-Win32 "CredWrite"
+    }
+  } finally {
+    $pinned.Free()
+  }
+}
+
+function Remove-CredentialValue([string]$Target) {
+  if ([SgwCredMan]::CredDelete($Target, [SgwCredMan]::CRED_TYPE_GENERIC, 0)) {
+    return $true
+  }
+
+  $code = Get-LastErrorCode
+  if ($code -eq 1168) {
+    return $false
+  }
+  Throw-Win32 "CredDelete"
+}
+
+$target = Get-TargetName
+
+switch ($Command) {
+  "get" {
+    [Console]::Out.Write((Read-CredentialValue $target))
+    break
+  }
+  "set" {
+    $value = [Console]::In.ReadToEnd()
+    Write-CredentialValue -Target $target -Value $value
+    break
+  }
+  "delete" {
+    $deleted = Remove-CredentialValue $target
+    [Console]::Out.WriteLine((@{ deleted = $deleted } | ConvertTo-Json -Compress))
+    break
+  }
+  "status" {
+    [Console]::Out.WriteLine((@{
+      supported = $true
+      target = $target
+      configured = Test-CredentialValue $target
+    } | ConvertTo-Json -Compress))
+    break
+  }
+}

package/dist/windows/s-gw-helper.cmd

@@ -0,0 +1,4 @@
+@echo off
+setlocal
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0s-gw-helper.ps1" %*
+exit /b %ERRORLEVEL%

package/dist/windows/s-gw-helper.ps1

@@ -0,0 +1,180 @@
+[CmdletBinding()]
+param(
+  [int]$Port = 8718,
+  [string]$ConsoleUrl = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+function Resolve-CliPath {
+  if ($env:SGW_CLI_PATH -and (Test-Path -LiteralPath $env:SGW_CLI_PATH)) {
+    return (Resolve-Path -LiteralPath $env:SGW_CLI_PATH).Path
+  }
+
+  $distDir = Split-Path -Parent $PSScriptRoot
+  $candidate = Join-Path $distDir "cli.js"
+  if (Test-Path -LiteralPath $candidate) {
+    return (Resolve-Path -LiteralPath $candidate).Path
+  }
+
+  throw "Unable to find s-gw CLI. Set SGW_CLI_PATH to dist\cli.js."
+}
+
+function Resolve-NodePath {
+  if ($env:SGW_NODE_PATH) {
+    return $env:SGW_NODE_PATH
+  }
+  return "node"
+}
+
+function New-ConsoleUrl {
+  if ($ConsoleUrl.Trim()) {
+    return $ConsoleUrl.Trim().TrimEnd("/") + "/"
+  }
+  return "http://127.0.0.1:$Port/"
+}
+
+function Quote-Arg([string]$Value) {
+  if ($Value.Length -eq 0) {
+    return '""'
+  }
+  return '"' + $Value.Replace('"', '\"') + '"'
+}
+
+function Invoke-CliJson([string[]]$Args) {
+  $psi = New-Object System.Diagnostics.ProcessStartInfo
+  $psi.FileName = $script:NodePath
+  $allArgs = @($script:CliPath) + $Args
+  $psi.Arguments = ($allArgs | ForEach-Object { Quote-Arg ([string]$_) }) -join " "
+  $psi.UseShellExecute = $false
+  $psi.RedirectStandardOutput = $true
+  $psi.RedirectStandardError = $true
+  $psi.CreateNoWindow = $true
+
+  $proc = [System.Diagnostics.Process]::Start($psi)
+  $stdout = $proc.StandardOutput.ReadToEnd()
+  $stderr = $proc.StandardError.ReadToEnd()
+  $proc.WaitForExit()
+  if ($proc.ExitCode -ne 0) {
+    throw ($stderr.Trim() + " " + $stdout.Trim()).Trim()
+  }
+  if (-not $stdout.Trim()) {
+    return $null
+  }
+  return $stdout | ConvertFrom-Json
+}
+
+function Start-Client([string]$Path = "") {
+  $clientScript = Join-Path $PSScriptRoot "s-gw-client.ps1"
+  $url = $script:BaseConsoleUrl
+  if ($Path) {
+    $url = $script:BaseConsoleUrl.TrimEnd("/") + "/" + $Path.TrimStart("/")
+  }
+  Start-Process `
+    -FilePath "powershell.exe" `
+    -ArgumentList @("-NoProfile", "-ExecutionPolicy", "Bypass", "-File", $clientScript, "-Port", [string]$Port, "-ConsoleUrl", $url) | Out-Null
+}
+
+function Get-PendingRequests {
+  try {
+    $pending = Invoke-CliJson @("requests", "--state", "pending", "--limit", "25")
+    if ($null -eq $pending) {
+      return @()
+    }
+    if ($pending -is [array]) {
+      return $pending
+    }
+    return @($pending)
+  } catch {
+    $script:LastError = $_.Exception.Message
+    return @()
+  }
+}
+
+function Add-MenuItem([System.Windows.Forms.ContextMenuStrip]$Menu, [string]$Text, [scriptblock]$Handler, [bool]$Enabled = $true) {
+  $item = New-Object System.Windows.Forms.ToolStripMenuItem
+  $item.Text = $Text
+  $item.Enabled = $Enabled
+  if ($Handler) {
+    $item.Add_Click($Handler)
+  }
+  [void]$Menu.Items.Add($item)
+  return $item
+}
+
+function Approve-FirstPending {
+  $pending = Get-PendingRequests
+  if ($pending.Count -eq 0) {
+    return
+  }
+  $request = $pending[$pending.Count - 1]
+  Invoke-CliJson @("approve", [string]$request.id) | Out-Null
+  $script:Notify.ShowBalloonTip(2500, "s-gw", "Approved $($request.id)", [System.Windows.Forms.ToolTipIcon]::Info)
+  Update-Menu
+}
+
+function Deny-FirstPending {
+  $pending = Get-PendingRequests
+  if ($pending.Count -eq 0) {
+    return
+  }
+  $request = $pending[$pending.Count - 1]
+  Invoke-CliJson @("deny", [string]$request.id) | Out-Null
+  $script:Notify.ShowBalloonTip(2500, "s-gw", "Denied $($request.id)", [System.Windows.Forms.ToolTipIcon]::Info)
+  Update-Menu
+}
+
+function Update-Menu {
+  $pending = Get-PendingRequests
+  $count = $pending.Count
+  $script:Menu.Items.Clear()
+
+  $status = if ($script:LastError) { "s-gw helper - check setup" } elseif ($count -eq 1) { "1 approval waiting" } else { "$count approvals waiting" }
+  Add-MenuItem $script:Menu $status $null $false | Out-Null
+  [void]$script:Menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator))
+
+  Add-MenuItem $script:Menu "Open s-gw" { Start-Client } | Out-Null
+  Add-MenuItem $script:Menu "Approve Queue" { Start-Client "approvals" } | Out-Null
+  Add-MenuItem $script:Menu "Refresh" { $script:LastError = ""; Update-Menu } | Out-Null
+  Add-MenuItem $script:Menu "Approve oldest request" { Approve-FirstPending } ($count -gt 0) | Out-Null
+  Add-MenuItem $script:Menu "Deny oldest request" { Deny-FirstPending } ($count -gt 0) | Out-Null
+  [void]$script:Menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator))
+  Add-MenuItem $script:Menu "Quit helper" {
+    $script:Timer.Stop()
+    $script:Notify.Visible = $false
+    $script:Notify.Dispose()
+    [System.Windows.Forms.Application]::Exit()
+  } | Out-Null
+
+  $script:Notify.Text = if ($count -gt 0) { "s-gw - $count approval(s) waiting" } else { "s-gw - no pending approvals" }
+  if ($script:LastPendingCount -ge 0 -and $count -gt $script:LastPendingCount) {
+    $script:Notify.ShowBalloonTip(3000, "s-gw approval required", "$count request(s) waiting for local approval.", [System.Windows.Forms.ToolTipIcon]::Info)
+  }
+  $script:LastPendingCount = $count
+}
+
+$script:CliPath = Resolve-CliPath
+$script:NodePath = Resolve-NodePath
+$script:BaseConsoleUrl = New-ConsoleUrl
+$script:LastError = ""
+$script:LastPendingCount = -1
+
+[System.Windows.Forms.Application]::EnableVisualStyles()
+$script:Menu = New-Object System.Windows.Forms.ContextMenuStrip
+$script:Notify = New-Object System.Windows.Forms.NotifyIcon
+$script:Notify.Icon = [System.Drawing.SystemIcons]::Shield
+$script:Notify.Text = "s-gw"
+$script:Notify.Visible = $true
+$script:Notify.ContextMenuStrip = $script:Menu
+$script:Notify.Add_DoubleClick({ Start-Client "approvals" })
+
+$script:Timer = New-Object System.Windows.Forms.Timer
+$script:Timer.Interval = 15000
+$script:Timer.Add_Tick({ Update-Menu })
+
+Update-Menu
+$script:Timer.Start()
+[System.Windows.Forms.Application]::Run()

package/docs/README.md

@@ -0,0 +1,23 @@
+# s-gw Documentation
+
+## Start Here
+
+- [Quick start](quickstart.md): build s-gw and run the disposable trust-loop demo.
+- [Architecture](architecture.md): components, data flow, and local process boundaries.
+- [Threat model](threat-model.md): intended guarantees, attacker assumptions, and non-goals.
+- [Deployment](deployment.md): platform support, setup, packaging, upgrade, and uninstall.
+
+## Integrations
+
+- [Agent integrations](integrations.md): Codex, Claude Code, Cursor, OpenCode, and VS Code configuration.
+- [Agent profiles](agents.md): known clients, aliases, config paths, and compatibility status.
+- [macOS Keychain and Windows Credential Manager](keychain.md): operating system credential-store handles.
+- [1Password](onepassword.md): optional `op://` reference-backed handles.
+
+## Security Details
+
+- [Secret detection](detection.md): local credential-pattern scanning and tokenization.
+- [Security policy](../SECURITY.md): private vulnerability reporting.
+- [Third-party notices](ui/THIRD_PARTY_NOTICES.md): bundled code, artwork, and licenses.
+
+The native app and local console expose the same local store and CLI behavior. Documentation should describe supported behavior rather than a specific UI layout unless the distinction matters.

package/docs/agents.md

@@ -0,0 +1,160 @@
+# Agent Support
+
+s-gw maintains a small profile for each known coding agent: canonical name, aliases, configuration paths, MCP shape, skills or plugin directories, and limitations. The registry structure is informed by DefenseClaw's connector model.
+
+This does not turn s-gw into a remote guardrail proxy. s-gw stays local and uses MCP tools plus local approval to keep raw credentials out of the agent.
+
+## CLI
+
+List known profiles:
+
+```bash
+s-gw agent list
+```
+
+Show one profile with an MCP snippet:
+
+```bash
+s-gw agent show codex
+s-gw agent show openclaw
+s-gw agent show claude-code
+```
+
+Render only the snippet:
+
+```bash
+s-gw agent mcp-snippet codex
+s-gw agent mcp-snippet openclaw
+s-gw agent mcp-snippet cursor
+```
+
+Show the Project CodeGuard hardening path for an agent:
+
+```bash
+s-gw agent codeguard-plan codex
+s-gw agent codeguard-plan claude-code
+s-gw agent codeguard-plan opencode
+```
+
+For source builds or development, override the command:
+
+```bash
+s-gw agent mcp-snippet codex \
+  --command node \
+  --arg /path/to/s-gw/dist/mcp-server.js \
+  --env SGW_HOME=~/.s-gw
+```
+
+The packaged default command is:
+
+```bash
+s-gw-mcp
+```
+
+## Guard Mode
+
+Use guard mode when launching a CLI coding agent from the terminal:
+
+```bash
+s-gw guard status
+s-gw run codex --dry-run -- -v
+s-gw run codex -- --ask-for-approval never
+s-gw guard run claude-code -- --help
+```
+
+Guard mode scans the launch environment, stores credential-looking values in the local encrypted ledger during a real run, and replaces the child process values with `<<SGW_SECRET:...>>` handles. It also sets `SGW_GUARD_MODE`, `SGW_GUARD_AGENT`, `SGW_GUARD_INSTRUCTIONS`, and `SGW_GUARD_TOKENIZED_ENV` for the launched process.
+
+Use `--command CMD` for agents without a safe default CLI launcher:
+
+```bash
+s-gw guard run cursor --command cursor --dry-run
+```
+
+`--dry-run` uses preview handles and does not write to the store. A real run may use `--allow-command CMD` to attach an initial approved-execution policy to any handles created from environment variables, but production policies should remain narrow.
+
+## Agent Profile Registry
+
+s-gw tracks the 13 first-class agents documented by DefenseClaw as of tag `0.8.3`: OpenClaw, ZeptoClaw, Claude Code, Codex, Hermes, Cursor, Windsurf, Gemini CLI, GitHub Copilot CLI, OpenHands, Antigravity, OpenCode, and OmniGent.
+
+Status is intentionally strict. `Supported` means s-gw has a documented stdio MCP path for the agent. `Profiled/manual` means s-gw knows the likely local config surface and can render a snippet, but setup should stay manual and should not be described as fully compatible until the app has passed a hands-on smoke test with that agent. `Planned/profiled` means the connector shape is useful for roadmap and UI inventory, but s-gw should not emit a normal MCP install snippet.
+
+| Profile | Agent | Status | MCP config surface | Notes |
+| --- | --- | --- | --- | --- |
+| `openclaw` | OpenClaw | Profiled/manual | `~/.openclaw/openclaw.json` | Manual write path; prefer OpenClaw config command/UI when available. |
+| `zeptoclaw` | ZeptoClaw | Profiled/manual | `~/.zeptoclaw/config.json`, `./.mcp.json` | Manual write path because ZeptoClaw owns config autosave. |
+| `claudecode` | Claude Code | Supported | `./.mcp.json` (project), `~/.claude.json` via `claude mcp add` | Standard stdio MCP. Use `claude mcp add` or `.mcp.json`, not `settings.json`. Alias: `claude-code`. |
+| `codex` | Codex | Supported | `~/.codex/config.toml`, `./.mcp.json` | Standard stdio MCP and packaged Codex plugin. |
+| `hermes` | Hermes Agent | Profiled/manual | `~/.hermes/config.yaml` | YAML snippet; no automatic patcher yet. |
+| `cursor` | Cursor | Supported | `./.cursor/mcp.json`, `~/.cursor/mcp.json` | Project-local config preferred. |
+| `windsurf` | Windsurf | Profiled/manual | `~/.codeium/windsurf/mcp_config.json`, `~/.codeium/windsurf/mcp.json` | Do not create guessed config paths. |
+| `geminicli` | Gemini CLI | Supported | `~/.gemini/settings.json`, `./.gemini/settings.json` | Alias: `gemini`. |
+| `copilot` | GitHub Copilot CLI | Supported | `~/.copilot/mcp-config.json`, `./.github/mcp.json`, `./.mcp.json` | Workspace config preferred. |
+| `openhands` | OpenHands | Profiled/manual | `~/.openhands/mcp.json` | Global MCP config; optional workspace hooks only when intentionally scoped. |
+| `antigravity` | Antigravity | Profiled/manual | `~/.gemini/config/mcp_config.json`, `./.agents/mcp_config.json` | MCP config is separate from global hook config. Alias: `agy`. |
+| `opencode` | OpenCode | Supported | `~/.config/opencode/opencode.json`, `opencode.json`, `.jsonc` variants | Top-level `mcp` map, not `mcpServers`. |
+| `omnigent` | OmniGent | Planned/profiled | `$OMNIGENT_CONFIG_HOME/config.yaml`, `~/.omnigent/config.yaml` | DefenseClaw uses a custom policy bridge, not a normal MCP server entry. |
+
+The registry also includes this general MCP client profile:
+
+| Profile | Agent | Status | MCP config surface |
+| --- | --- | --- | --- |
+| `vscode` | VS Code / GitHub Copilot Agent Mode | Supported | `./.vscode/mcp.json` |
+
+## Project CodeGuard Layer
+
+Project CodeGuard is useful as a companion layer, not a replacement for s-gw. CodeGuard gives agents secure coding guidance and review rules; s-gw keeps credentials local, tokenizes them into handles, and requires local authorization before secret-backed actions run.
+
+The current CodeGuard project is under CoSAI/OASIS at `https://github.com/cosai-oasis/project-codeguard`. s-gw does not vendor CodeGuard's CC BY rule content; it points users to upstream release artifacts so rules can be installed, pinned, and audited intentionally.
+
+Use:
+
+```bash
+s-gw agent codeguard-plan AGENT
+```
+
+Recommended current paths:
+
+| Agent | CodeGuard route | Install surface |
+| --- | --- | --- |
+| Claude Code | Plugin marketplace | `/plugin install codeguard-security@project-codeguard` |
+| Codex | Agent Skill | `./.agents/skills/codeguard` |
+| Cursor | Rule files | `./.cursor/rules` |
+| Windsurf | Rule files | `./.windsurf/rules` |
+| GitHub Copilot CLI / VS Code Copilot | Repository instructions | `./.github/instructions` |
+| Antigravity | Rule files | `./.agents/rules` |
+| OpenCode | Agent Skill | `./.opencode/skills/codeguard` |
+| OpenClaw | Agent Skill | `./.openclaw/skills/codeguard` |
+| Hermes | Agent Skill | `./.hermes/skills/codeguard` |
+
+Codex deserves extra care: CodeGuard's current package uses project-local `.agents/skills/codeguard`. Project-local `.codex/skills` was used by older packages and should be treated as stale for CodeGuard. User-level Codex skills under `~/.codex/skills` are still a separate Codex home-level surface.
+
+## Agent Enforcement Surfaces
+
+MCP registration and an agent's enforcement surface are separate concerns. MCP gives an agent tools; hooks, plugins, and policies determine whether a product can observe prompts, tool calls, command execution, or post-tool output. The table records those distinctions without claiming that s-gw installs every hook.
+
+| Agent | DefenseClaw hook style | Config surface | Native ask? | s-gw implication |
+| --- | --- | --- | --- | --- |
+| OpenClaw, ZeptoClaw | Proxy connectors | App-owned proxy/config files | Proxy-owned | Use local MCP registration; remote proxying is outside s-gw's credential boundary. |
+| Claude Code | Native hooks | `~/.claude/settings.json` | PreToolUse | Keep warning users that MCP config is `.mcp.json`/`~/.claude.json`, not `settings.json`. |
+| Codex | Native hooks plus OTel/notify | `~/.codex/config.toml` | Permission flow | Current support covers local MCP registration and s-gw approval for credential-backed actions. |
+| Cursor | Native hooks | `~/.cursor/hooks.json` | `beforeShellExecution`, `beforeMCPExecution` | Hook installation is not currently managed by s-gw. |
+| Windsurf | Cascade hooks | `~/.codeium/windsurf/hooks.json` | No | s-gw approval remains the supported credential control path. |
+| Gemini CLI | Native hooks | `~/.gemini/settings.json` | No | MCP and hooks share a file, so installer must preserve unrelated settings carefully. |
+| GitHub Copilot CLI | Hook JSON | `~/.copilot/hooks/defenseclaw.json`, `./.github/hooks/defenseclaw.json` | `preToolUse` | s-gw currently documents MCP setup rather than installing hook files. |
+| OpenHands | Hook JSON | `~/.openhands/hooks.json`, optional `./.openhands/hooks.json` | No | Global hook install by default; workspace install only on explicit request. |
+| Antigravity | Native lifecycle hooks | `~/.gemini/config/hooks.json` | `decision=ask` on pre-action events | Write only the canonical global hook file to avoid duplicate firings. |
+| OpenCode | Auto-loaded JS plugin | `~/.config/opencode/plugins/defenseclaw.js` | No | Hook installer would be a managed plugin, not a JSON hook entry. |
+| OmniGent | Custom Python policy API | `$OMNIGENT_CONFIG_HOME/config.yaml`, `~/.omnigent/config.yaml` | Pre-action policy phases | Needs a real s-gw policy bridge before public compatibility claims. |
+
+## Integration Boundary
+
+DefenseClaw connectors often patch hooks, proxy routes, telemetry, and subprocess shims. s-gw intentionally starts narrower:
+
+- register a local stdio MCP server;
+- launch CLI agents with credential-like environment values replaced by SGW handles;
+- expose tokenization and handle metadata;
+- require local user approval before secret-backed execution;
+- inject secrets only into local child processes;
+- sanitize command output before returning it to the agent.
+
+s-gw does not automatically modify agent configuration yet. Use `s-gw agent mcp-snippet` to render a configuration, review it, and apply it through the agent's supported configuration path.

package/docs/architecture.md

@@ -0,0 +1,72 @@
+# Architecture
+
+s-gw is a local credential broker. Its storage, approval, execution, and user interfaces run on the same machine as the coding agent.
+
+```mermaid
+flowchart LR
+    Agent["Coding agent or MCP client"] --> MCP["s-gw MCP server"]
+    CLI["s-gw CLI"] --> Store["Encrypted ledger"]
+    MCP --> Store
+    Store --> Review["Native app / menu helper / local console"]
+    Review --> Store
+    Store --> Broker["Approval broker"]
+    Keychain[("Keychain / Credential Manager") ] --> Broker
+    OnePassword[("Optional 1Password source") ] --> Broker
+    Broker --> Runner["Rust execution core"]
+    Runner --> Sanitizer["Bounded output sanitizer"]
+    Sanitizer --> MCP
+```
+
+## Components
+
+### CLI And MCP Server
+
+The TypeScript CLI owns setup, handle enrollment, request creation, approval orchestration, diagnostics, and integration output. The stdio MCP server exposes the narrower agent-facing surface: scan data, list or describe non-secret handles, create requests, and execute requests that have already been approved.
+
+### Encrypted Ledger
+
+The ledger stores handle metadata, encrypted local values or credential-store pointers, request manifests, reusable grants, policy rules, and audit events. Its unlock material comes from the operating system credential store during normal desktop use. `SGW_MASTER_PASSPHRASE` exists for tests and controlled automation.
+
+### Credential Backends
+
+- **macOS Keychain:** the preferred backend on macOS.
+- **Windows Credential Manager:** the preview backend on Windows.
+- **Encrypted local value:** compatibility and test path.
+- **1Password reference:** optional source backed by the local `op` CLI, with an encrypted local cache for a bounded reusable approval.
+
+Backends resolve values only inside the local approved execution path. Agent-facing APIs return handles and metadata.
+
+### Approval Surfaces
+
+The native macOS app, standalone menu helper, local web console, and CLI read and update the same request records. A request includes the handle, action kind, command or SSH destination, environment binding, working directory, agent identity, reason, and state.
+
+Reusable approvals are matched against their stored scope. They are not a general unlock for the credential store.
+
+### Local Runner
+
+The approval broker claims the request, validates the handle policy again, and resolves credential values locally. Approved environment commands are then sent to the compiled `sgw-core` runner over stdin using protocol version 1. Credential values never appear in runner arguments or its inherited environment.
+
+The Rust runner clears the child environment, restores a small allowlist of ordinary process variables, injects only approved credential bindings, enforces the timeout, captures bounded stdout and stderr, replaces known values with handles, and returns a proof-bound result. The broker rejects malformed responses, raw credential output, or an invalid proof before updating the request record.
+
+Owned SSH sessions use the TypeScript execution path. Platform-native packages include the Rust runner and select it automatically for approved environment commands. A Windows preview assembled on macOS uses the TypeScript compatibility path because it cannot contain a Windows-native runner; Windows builds include `sgw-core.exe`. `SGW_EXECUTION_ENGINE=rust` can require the compiled runner, while `SGW_EXECUTION_ENGINE=typescript` selects the compatibility path explicitly.
+
+### User Interfaces
+
+The React console is served on loopback and requires a per-session token for state-changing requests. The native macOS app and menu helper use the installed CLI and local store. The Windows preview client hosts the loopback console in a browser app window and provides a tray helper for queue actions.
+
+## Process Boundaries
+
+- MCP uses stdio and does not expose a remote credential API.
+- The browser console binds to `127.0.0.1` by default.
+- New secrets and unlock values are accepted over stdin, not command-line arguments.
+- Approved environment-command credentials cross from the broker to `sgw-core` over a private stdin pipe, not process arguments or inherited environment variables.
+- Secret-backed commands run as child processes of the local s-gw process under the current operating system user.
+- s-gw-owned SSH sessions use private control sockets under the local s-gw home.
+
+See the [threat model](threat-model.md) for what these boundaries do and do not protect.
+
+## Deployment Models
+
+The open-source product is a complete standalone endpoint: Rust core, local storage, approvals, policies, agent integrations, audit history, and desktop clients. Independent local installations do not require a control plane.
+
+Team deployments can add a control plane for endpoint fleets, shared policy, delegated approvals, identity, compliance retention, and enterprise vault references. The intended boundary exchanges handle metadata, signed policy, approval state, and sanitized events. Raw credentials remain in the endpoint credential store or an enterprise vault.