skalpel 2.0.24 → 3.0.1

package/INSTALL.md

@@ -0,0 +1,103 @@
+# Install and bundling — `skalpel` and `skalpeld`
+
+The `skalpel` npm package is the canonical distribution surface for the Skalpel client on a developer's machine. The package contains two executables: `skalpel`, the Bubble Tea terminal UI specified in `SPEC.md` (in this repo) and `docs/RUN_CLIENT_LOCALLY.md` (also in this repo), and `skalpeld`, the local proxy and daemon. Installing one always installs the other; the two are released, signed, and versioned as a single bundle. A user who runs `npx skalpel`, `npm install -g skalpel`, or pulls a GitHub Releases tarball receives both binaries in a single transaction. There is no separate `skalpeld` package, no separate version cadence, and no "TUI without daemon" install path.
+
+This document is the canonical specification for what gets installed where, how the first-run flow lands the user on the Engines tab, and how updates and uninstalls are handled. See `SPEC.md` for the TUI specification, `docs/RUN_CLIENT_LOCALLY.md` for the dev workflow, and the upstream infrastructure / cross-surface-contract documents (when available) for bundle composition and auth-handoff details.
+
+The bundling commitment is a product decision before it is an implementation decision. A user who installs the TUI receives the daemon in the same transaction because the configurator (TUI) and the proxy (`skalpeld`) are two halves of the same product surface. Splitting them into independently versioned packages would introduce a class of "TUI-newer-than-daemon" or "daemon-newer-than-TUI" failures that no recovery clause in `SPEC.md` §8 is designed to handle. The bundle is the unit of release; the version is the unit of identity; the install path is the unit of choice.
+
+## What gets installed
+
+The npm package places two executables on the user's machine. Both arrive together; neither is shipped without the other.
+
+| Binary | Role | On-disk location |
+|---|---|---|
+| `skalpel` | Bubble Tea terminal UI; the configurator the user invokes by typing `skalpel` in a shell. | A directory on the user's `PATH`. For `npx`, this is npm's transient cache. For `npm install -g`, this is the npm global prefix's `bin/` directory (typically `/usr/local/bin/skalpel` on macOS and Linux, `%AppData%\npm\skalpel.cmd` on Windows). |
+| `skalpeld` | Local proxy/daemon; intercepts traffic from coding agents (Cursor, Claude Code, Codex), applies engines, and forwards to upstream providers. | Co-located with `skalpel` in the same `bin/` directory. Per-OS service registration (launchd agent on macOS, systemd user unit on Linux, Task Scheduler entry on Windows) is performed by the `postinstall` script so the daemon survives reboot; see "Daemon lifecycle on subsequent launches" below and `../../Skalpel_Infrastructure/INFRASTRUCTURE.md` for the platform constraints. |
+
+Both binaries are produced from the same release workflow named in `INFRASTRUCTURE.md`'s CLI Distribution section. Both are signed keylessly via Sigstore / cosign. Both carry the same version string. Mismatch by version is impossible by construction on a machine that received either binary via a supported install path.
+
+### Platform support
+
+The release workflow targets three platforms in v1: macOS (arm64 and amd64), Linux (amd64; arm64 as a follow-on), and Windows (amd64). Each platform receives its own pair of binaries built from the same source revision. The npm package selects the right pair at install time based on the user's `os` and `cpu`; the GitHub Releases tarballs are named per-platform and the user picks. The configuration directory paths and service-registration entry points named elsewhere in this document differ per platform; the bundling and version-coupling commitments do not.
+
+### Configuration directory
+
+The configuration directory is per-OS, per `SPEC.md` §7. Both binaries read it: the TUI for `auth.json` and `config.toml`, the daemon for the same files plus its socket and logfile path. The directory is created by the wizard on first run and is owned by the user. It is not part of the npm package; it is created by the binaries on first invocation and survives uninstalls so that reinstalls can resume.
+
+## Install paths
+
+Three first-class install paths are supported. Each delivers both binaries; none can deliver one without the other.
+
+- **`npx skalpel`** — the zero-install path. npm fetches the package on demand and runs the `skalpel` binary. `skalpeld` is materialized in the same npx cache and is reachable on the same `PATH`-like resolution that npx uses for the lifetime of the invocation. This is the recommended path for users running Skalpel for the first time.
+- **`npm install -g skalpel`** — the persistent-install path. The package is installed into npm's global prefix; both binaries are placed in the global `bin/` directory and become available system-wide. Subsequent invocations resolve `skalpel` and `skalpeld` from `PATH` without the npm overhead. Recommended for users who want the binaries co-located with their other CLI tools.
+- **GitHub Releases tarballs** — the air-gapped path. Each release attaches per-platform tarballs containing both binaries plus their cosign signatures and checksums (per `INFRASTRUCTURE.md`'s CLI Distribution section, which mandates keyless Sigstore signing for every release artifact). Recommended for users on a machine that cannot reach the public npm registry, or for environments where supply-chain verification is performed manually before placing binaries on `PATH`.
+
+All three paths produce identical binaries — same SHAs, same cosign signatures, same version metadata. The choice between them is operational, not functional.
+
+## First-run flow
+
+The first-run flow assumes the user has obtained an `sk-skalpel-*` API key on Web (per the Auth handoff section of `../../design-dockets/cross-surface-contract.md`). The flow is:
+
+1. The user runs `npx skalpel` (or `skalpel` after a global install). The npm package is materialized; both binaries are present.
+2. The TUI detects the absence of `auth.json` and enters the install wizard. The wizard prompts the user to paste the API key copied from Web. The plaintext value is shown on Web exactly once at creation time; the user pastes it here.
+3. The wizard writes `auth.json` to the per-OS configuration directory (per `SPEC.md` §7). The file is owned by the user with `0600` permissions.
+4. The wizard invokes `skalpeld` to start the daemon. The TUI shows the `Starting skalpeld…` splash for up to three seconds (per spec §8.5).
+5. Once the daemon is reachable, the TUI lands the user on the Engines tab. The matrix renders for whatever agents the daemon has detected so far. If no agents have been opened since installation, the empty-state message from spec §3.2 is shown.
+
+This flow corresponds to Journey 1 — First launch, fresh authentication — in `SPEC.md`. That narrative describes what the user feels at each step; this document describes what the install machinery actually does.
+
+If the user runs `skalpel` without first obtaining an API key, the TUI exits per spec §8.4 with a stderr pointer at `skalpel login`. The wizard above is the path for users who arrived through the post-signup install hub on Web; users with broken or missing auth state are returned to the shell.
+
+An alternative first-run flow uses `skalpel login` from the shell directly. That command runs a device-code flow against Cognito (per the Auth handoff section of the cross-surface contract) and writes `auth.json` without the user having to paste an API key. The two flows produce equivalent on-disk state; the API-key-paste flow is the one a user lands in when arriving from the Web post-signup install hub, and the device-code flow is the one a user runs when reauthenticating an account that has already been signed in on this machine before.
+
+## Daemon lifecycle on subsequent launches
+
+On every launch after the first, the TUI checks whether `skalpeld` is reachable. If it is, the TUI proceeds to the Engines tab without further interaction. If it is not, the TUI attempts to start it (per spec §8.5) and shows the `Starting skalpeld…` splash for up to three seconds. If the daemon does not come up in that window, the TUI proceeds with the daemon-unreachable banner and the user is offered a `[r]` retry affordance.
+
+The TUI is not a process supervisor. Per `SPEC.md` §01: the TUI tries to start the daemon at launch and surfaces the daemon's state via the banner, but there is no "stop daemon," "restart daemon," or "view daemon logs" control in the TUI; those are shell-level concerns. The install machinery makes both binaries available; the runtime relationship between them is the TUI's start-on-launch attempt and nothing more.
+
+Per-OS service registration is performed by the npm `postinstall` script (`postinstall/lib/service-register.js`). On macOS the script renders and loads a launchd agent (`com.skalpel.skalpeld.plist`) and kickstarts it via `launchctl`; on Linux the script writes a systemd user unit (`skalpeld.service`) and starts it via `systemctl --user`; on Windows the script registers a Task Scheduler entry (`Task.xml`) and runs it via `schtasks /Run`. The `postinstall` script also starts the daemon immediately on first install so the user does not have to wait for the next TUI launch to bring `skalpeld` online; subsequent boots rely on the registered service entry, with the TUI's start-on-launch attempt as a defence-in-depth fallback. Both the bundling commitment (atomic install of TUI + daemon) and the TUI's runtime behaviour on launch are independent of the service registration mechanism.
+
+## Updates
+
+`npx skalpel@latest` and `npm update -g skalpel` are the two update paths. Both update both binaries atomically: the new `skalpel` and the new `skalpeld` arrive together, and the old `skalpel` and old `skalpeld` are replaced together. There is no window during which the binaries are at different versions on disk.
+
+The CLI auto-update polling described in `INFRASTRUCTURE.md` (CLI Distribution, the `cli/latest` endpoint) surfaces a non-blocking notice when a newer version is available. The user runs the update command themselves; the TUI does not perform an in-place upgrade. After an update, the next `skalpel` invocation launches the new TUI, which in turn starts the new `skalpeld` if needed.
+
+GitHub Releases tarball users update by downloading the new tarball, verifying signatures and checksums, and replacing the binaries on `PATH`. Both replacements happen as a single user-initiated operation; partial updates are not a supported state.
+
+A user who has rolled back to a previous version (by running `npm install -g skalpel@<older>` or by replacing tarball binaries with archived ones) lands at a coherent older bundle: the older `skalpel` and the older `skalpeld` arrive together. There is no roll-back-the-TUI-only or roll-back-the-daemon-only operation. The same atomicity that protects forward updates protects rollbacks.
+
+## Uninstall
+
+`npm uninstall -g skalpel` removes both binaries. There is no separate uninstall command for `skalpeld`; the package is the unit of removal. Before npm removes the binaries it fires the package's `preuninstall` hook, which invokes `node postinstall/index.js --uninstall`; that pass removes the rc-file managed-block injected on install (so the user's shell stops pointing at the now-defunct local proxy port) and unregisters the per-OS service entry (so `launchctl`, `systemctl --user`, or `schtasks` stops trying to start a daemon whose binary is about to vanish). The shim and registration cleanup happen before the binaries themselves are removed; an interrupted uninstall leaves a coherent intermediate state.
+
+`npx skalpel` users have no global install to uninstall; the npx cache is cleaned by npm on its own schedule. For an `npx`-only user who wants to clean up shell rc-file and service registration without waiting on cache eviction, running `node postinstall/index.js --uninstall` from the package directory performs the same cleanup the `preuninstall` hook would.
+
+User data is **not** removed by uninstall. The configuration directory (`config.toml` and `auth.json`) persists on disk after the binaries are gone. This is deliberate: a user reinstalling Skalpel on the same machine should find their engine toggles and active organization preserved. To remove user data manually, delete the per-OS configuration directory named in `SPEC.md` §7.
+
+## Version coupling
+
+`skalpel` and `skalpeld` carry the same version string at all times. The release workflow produces both from the same git tag; the npm package's `version` field, the binaries' embedded version metadata, and the cosign signatures all reference the same value. There is no path by which the two could diverge on a machine that received either via a supported install path.
+
+When the TUI connects to the daemon at launch, the handshake includes a version exchange. If the version reported by `skalpeld` does not match the version embedded in `skalpel` — a state that should be unreachable through the supported install paths — the TUI enters a degraded state per `SPEC.md` §8 and surfaces a banner instructing the user to reinstall the bundle. The handshake is a defence in depth; the install paths are designed so that the handshake should never fire on a mismatch.
+
+The handshake is also where the TUI reads the daemon's engine list and the daemon's per-agent detection results (per `SPEC.md` §6 and §9). A version-coupled handshake is also a guarantee that the TUI is reading those results from a daemon whose schema it understands. When the bundle promises versions match, the TUI does not need a defensive parse-and-recover path for the daemon's responses; the schema is whatever the bundle's joint version says it is.
+
+## Open questions
+
+A small set of bundling questions are recorded here for the build phase. Each will be resolved before v1 ships; none affect the design commitments above.
+
+- **`npx` cache eviction and version-pinning UX.** `npx skalpel` caches per-version; a user who runs `npx skalpel@1.2.3` after `1.2.4` has shipped continues to execute `1.2.3` until npm's cache resolves. The auto-update notice surfaces in the TUI, but the underlying npx semantics are an open ergonomic question.
+- **Signed-link pre-population of the API key.** Whether the post-signup install path emits a signed link that pre-populates the `npx skalpel` wizard with the user's API key, or whether the user pastes the key by hand, is recorded in `../../design-dockets/cross-surface-contract.md` as an open question. The latter is the safer default; the former would shorten the first-run flow by one step.
+- **Bundle size budget.** The two binaries together set a download-size budget for first-time `npx` users; whether to ship a slim TUI front-end and a separately-downloaded `skalpeld` payload via a `postinstall` fetch (still in the same npm transaction) or to ship both in the package tarball directly is a build-phase decision. Either approach preserves the bundling commitment because both binaries are still resolved and authenticated within the same install operation.
+- **Install-time telemetry.** Whether the install path emits any telemetry event (e.g., "first install completed") is open. The TUI itself does not phone home in v1 (per the privacy stance in `SPEC.md` §05); whether the install wizard shares that posture or whether anonymous install counts are acceptable for release-quality measurement is a build-phase decision.
+- **Windows install ergonomics.** Whether `npx skalpel` on Windows requires Windows Terminal or a recent PowerShell to render the Bubble Tea TUI's adaptive colours and key bindings cleanly, and whether a fallback message should explain the requirement, is open. The bundling commitment is platform-agnostic; the first-run experience may not be.
+
+## References
+
+- `SPEC.md` — TUI specification: §1 (goals and non-goals; Install/uninstall flow is named as a non-goal there with a pointer here), §7 (configuration directory and file layout), §8 (degraded states and banners, including the version-mismatch banner), §16 (Install and distribution; cross-links here as the canonical source).
+- `SPEC.md` — Skalpel TUI design dockets: §01 (the daemon non-supervisor stance), §03 Journey 1 (first-launch fresh-authentication flow that this document's first-run flow corresponds to), §05 (privacy stance referenced in the install-time telemetry open question).
+- `../../design-dockets/cross-surface-contract.md` — Cross-surface contract: the Auth handoff section (machine-client identity, the `npx skalpel` install wizard arriving in the same transaction as the daemon), the ownership matrix's Post-signup install row.
+- `../../Skalpel_Infrastructure/INFRASTRUCTURE.md` — CLI Distribution section (npm, GitHub Releases, Sigstore signing, the `cli/latest` auto-update endpoint, emergency-release fallback path).

package/LICENSE

@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2025 Skalpel AI
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-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. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 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 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 Support. 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 support.
+
+   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 SkalpelAI Inc.
+
+   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/README.md

@@ -1,188 +1,26 @@
-# Skalpel
+# skalpel
 
-Optimize Claude Code prompts to reduce credit usage. Skalpel sits between Claude Code and the Anthropic API, optimizing prompts before they reach the provider — saving you money without changing how you work.
+Skalpel is the local proxy and terminal UI for coding agents — Cursor, Claude Code, Codex, and others. It runs as two binaries on your machine: `skalpel`, a Bubble Tea TUI configurator, and `skalpeld`, the local daemon that intercepts agent traffic, applies engines, and forwards to upstream providers. The two ship as a single npm package and are always installed together.
 
-## How It Works
+## Install and first run
 
-```
-Claude Code  -->  Skalpel Proxy (local)  -->  Skalpel Backend (AWS)  -->  Anthropic API
-                  Intercepts requests          Optimizes prompts           Returns response
-                  Adds tracking headers        Reduces token usage
-```
-
-1. A local proxy runs on your machine (port 18100)
-2. Claude Code is configured to send API requests to the proxy instead of `api.anthropic.com`
-3. The proxy forwards requests to the Skalpel backend, which optimizes prompts for lower token usage
-4. The optimized request is sent to Anthropic, and the response streams back to Claude Code
-
-Your Anthropic API key stays in the request chain — Skalpel never stores it.
+After signing up at [skalpel.ai](https://skalpel.ai) and copying your `sk-skalpel-*` API key:
 
-## Quick Start
-
-One command to install, detect Claude Code, and start optimizing:
-
-```bash
-npx skalpel --api-key sk-skalpel-YOUR_KEY --auto
 ```
-
-This will:
-- Start the local proxy on ports 18100 (Anthropic) and 18101 (OpenAI)
-- Detect coding agents on your machine
-- Configure Claude Code and Codex agents automatically
-- Set shell environment variables in your `.bashrc`/`.zshrc`
-- Begin optimizing API traffic immediately
-
-### Interactive Setup
-
-For a guided setup with prompts:
-
-```bash
 npx skalpel
 ```
 
-The wizard walks you through API key entry, agent detection, and proxy configuration.
-
-### Manual Setup
-
-```bash
-# 1. Start the proxy
-npx skalpel start
-
-# 2. Run the setup wizard to configure Claude Code
-npx skalpel setup
-
-# 3. Verify everything is working
-npx skalpel doctor
-```
-
-## What Gets Configured
-
-### Claude Code
-
-Claude Code is auto-configured during setup. `ANTHROPIC_BASE_URL` is set in `~/.claude/settings.json` to route API calls through the proxy. Only API endpoints (`/v1/messages`, `/v1/complete`) are routed through Skalpel for optimization; auth endpoints pass directly to Anthropic.
-
-### Shell Environment (`~/.bashrc`, `~/.zshrc`)
-
-Environment variables are added for tools that read them directly:
-
-```bash
-# BEGIN SKALPEL PROXY - do not edit manually
-export ANTHROPIC_BASE_URL="http://localhost:18100"
-export OPENAI_BASE_URL="http://localhost:18101"
-# END SKALPEL PROXY
-```
-
-### Proxy Config (`~/.skalpel/config.json`)
-
-```json
-{
-  "apiKey": "sk-skalpel-YOUR_KEY",
-  "remoteBaseUrl": "http://skalpel-production-554359744.us-west-2.elb.amazonaws.com",
-  "anthropicPort": 18100,
-  "openaiPort": 18101
-}
-```
-
-## CLI Commands
-
-| Command | Description |
-|---|---|
-| `npx skalpel` | Run the setup wizard |
-| `npx skalpel start` | Start the proxy |
-| `npx skalpel stop` | Stop the proxy |
-| `npx skalpel status` | Show proxy status and uptime |
-| `npx skalpel doctor` | Verify configuration and connectivity |
-| `npx skalpel logs` | View proxy logs |
-| `npx skalpel logs -f` | Follow proxy logs in real time |
-| `npx skalpel uninstall` | Remove proxy, configs, and shell modifications |
+`npx` materializes both binaries, walks you through pasting the API key, starts `skalpeld`, and lands you on the Engines tab. To install persistently:
 
-### Flags
-
-| Flag | Description |
-|---|---|
-| `--api-key <key>` | Provide Skalpel API key (skips interactive prompt) |
-| `--auto` | Non-interactive mode (requires `--api-key`) |
-
-## Streaming Support
-
-Skalpel fully supports Anthropic's SSE streaming protocol. When Claude Code sends a streaming request (`"stream": true`), the proxy:
-
-- Detects the streaming flag in the request body
-- Forwards to the backend with all original headers
-- Pipes SSE events (`message_start`, `content_block_delta`, `message_stop`) directly back to Claude Code
-- Preserves upstream headers like `anthropic-request-id`
-
-No buffering, no modification of the stream — chunks flow through in real time.
-
-## Headers
-
-The proxy adds these headers to every request forwarded to the Skalpel backend:
-
-| Header | Value | Purpose |
-|---|---|---|
-| `X-Skalpel-API-Key` | Your Skalpel key | Backend authentication |
-| `X-Skalpel-Source` | `claude-code` | Traffic source identification |
-| `X-Skalpel-Agent-Type` | `claude-code` | Agent type for optimization routing |
-| `X-Skalpel-SDK-Version` | `proxy-1.0.0` | SDK version tracking |
-
-The original `x-api-key` header (your Anthropic key) is forwarded as-is.
-
-## Codex Support
-
-Skalpel also supports OpenAI Codex on port 18101. The same `--auto` flow detects and configures both agents if present.
-
-## SDK Integration
-
-For programmatic use in your own applications:
-
-```typescript
-import { createSkalpelClient } from 'skalpel';
-import Anthropic from '@anthropic-ai/sdk';
-
-const client = createSkalpelClient(new Anthropic(), {
-  apiKey: process.env.SKALPEL_API_KEY!,
-});
-
-const response = await client.messages.create({
-  model: 'claude-sonnet-4-20250514',
-  max_tokens: 1024,
-  messages: [{ role: 'user', content: 'Hello' }],
-});
 ```
-
-See the [API Reference](#api-reference) for all SDK options.
-
-## API Reference
-
-### `createSkalpelClient<T>(client: T, options: SkalpelClientOptions): T`
-
-Wraps an existing OpenAI or Anthropic client. All API calls route through the Skalpel proxy with automatic fallback on errors.
-
-### `createSkalpelAnthropic(options): Promise<Anthropic>`
-
-Creates a pre-configured Anthropic client pointing at the Skalpel proxy.
-
-### `createSkalpelOpenAI(options): Promise<OpenAI>`
-
-Creates a pre-configured OpenAI client pointing at the Skalpel proxy.
-
-### Configuration Options
-
-```typescript
-interface SkalpelClientOptions {
-  apiKey: string;                  // Skalpel API key (sk-skalpel-*)
-  workspace?: string;              // Workspace ID
-  baseURL?: string;                // Proxy URL (default: production ALB)
-  fallbackOnError?: boolean;       // Fall back to direct provider (default: true)
-  timeout?: number;                // Request timeout in ms (default: 30000)
-  retries?: number;                // Max retries (default: 2)
-}
+npm install -g skalpel
 ```
 
-## Uninstall
+Both `skalpel` and `skalpeld` are placed on your `PATH`. For details on what gets installed where, per-OS service registration, updates, and uninstall, see [INSTALL.md](./INSTALL.md).
 
-```bash
-npx skalpel uninstall
-```
+## Links
 
-This removes the proxy and cleans up shell environment variables. If a previous version of Skalpel modified `~/.claude/settings.json`, uninstall will also clean up those changes.
+- Homepage: https://skalpel.ai
+- Documentation: see `INSTALL.md` and `SPEC.md` in this repo
+- Issues: https://github.com/skalpelai/Skalpelai_Client/issues
+- License: Apache-2.0 (see [LICENSE](./LICENSE))

package/design-tokens.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "design-tokens.schema.json",
+  "version": 1,
+  "themes": {
+    "tokyo-night-storm": {
+      "base": "#1a1b26",
+      "mantle": "#16161e",
+      "crust": "#16161e",
+      "surface0": "#16161e",
+      "surface1": "#1f2335",
+      "surface2": "#24283b",
+      "overlay0": "#3b4261",
+      "overlay1": "#565f89",
+      "overlay2": "#737aa2",
+      "text": "#c0caf5",
+      "subtext0": "#a9b1d6",
+      "subtext1": "#a9b1d6",
+      "lilac": "#bb9af7",
+      "pink": "#f7768e",
+      "red": "#f7768e",
+      "maroon": "#f7768e",
+      "peach": "#ff9e64",
+      "lemon": "#e0af68",
+      "mint": "#9ece6a",
+      "teal": "#73daca",
+      "sky": "#7aa2f7",
+      "sapphire": "#7aa2f7",
+      "blue": "#7aa2f7",
+      "lavender": "#bb9af7"
+    }
+  },
+  "semantic": {
+    "tab.dashboard": "tokyo-night-storm.lilac",
+    "tab.engines": "tokyo-night-storm.sky",
+    "tab.sessions": "tokyo-night-storm.pink",
+    "tab.account": "tokyo-night-storm.mint",
+    "tab.logs": "tokyo-night-storm.lemon",
+    "selection.bg": "tokyo-night-storm.lilac",
+    "selection.fg": "tokyo-night-storm.crust",
+    "border.dim": "tokyo-night-storm.overlay0",
+    "footer.text": "tokyo-night-storm.overlay1",
+    "section.cost": "tokyo-night-storm.pink",
+    "section.engine": "tokyo-night-storm.lilac",
+    "section.quality": "tokyo-night-storm.mint",
+    "level.error": "tokyo-night-storm.red",
+    "level.warn": "tokyo-night-storm.lemon",
+    "level.info": "tokyo-night-storm.sky",
+    "level.success": "tokyo-night-storm.mint",
+    "level.debug": "tokyo-night-storm.overlay0"
+  }
+}