pi-career 0.1.0 → 0.3.0

package/README.md

@@ -1,159 +1,508 @@
 # pi-career
 
-Self-contained [Pi package](https://github.com/earendil-works/pi) for deterministic Career Core workflows on explicitly supported native targets.
+[![npm version](https://img.shields.io/npm/v/pi-career.svg)](https://www.npmjs.com/package/pi-career)
+[![npm downloads](https://img.shields.io/npm/dm/pi-career.svg)](https://www.npmjs.com/package/pi-career)
+[![CI](https://github.com/revazi/pi-career/actions/workflows/ci.yml/badge.svg)](https://github.com/revazi/pi-career/actions/workflows/ci.yml)
+[![license: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license-and-provenance)
 
-This publicly readable Git repository owns the Pi adapter, package-owned runtime artifacts and resolver, Pi package metadata, Pi-facing Agent Skill, build/package tests, and integration guidance. Career Core remains authoritative for operations, algorithms, versioned JSON schemas, errors, evidence, warnings, uncertainty, ordering, and assisted/non-authoritative semantics.
+`pi-career` is a [Pi package](https://github.com/earendil-works/pi) for deterministic resume analysis and conservative vacancy matching, with an optional model-assisted workflow for reviewed resume improvements.
 
-## Surface and non-scope
+The package's command handlers do not call a model/provider. `/career-workbench` prepares a visible private prompt in Pi's editor, while `/career-review` prepares only an ephemeral review handle and explicitly selected canonical IDs; only the user's later submission invokes the selected Pi model/provider. At runtime, pi-career never uses a Career Core source checkout or Cargo build. Its optional maintainer compatibility test may read an explicitly supplied, reviewed Core fixture checkout.
 
-The package preserves exactly three native tools:
+It gives you:
 
-- `career_core_discover`
-- `career_core_resume`
-- `career_core_job`
-
-On supported targets it also provides deterministic slash commands:
-
-- `/career-setup`
-- `/career-library`
-- `/career-vacancy`
-- `/career-match`
-- `/career-analyze`
+- local slash commands for setting up a resume library, analyzing originals, and matching them to a vacancy;
+- one compact managed agent tool, `career_run`, for guided work after the deterministic baseline;
+- a visible workbench handoff that never sends private resume text until you review and submit it yourself;
+- bounded TUI inspection and explicit selection of Core-reviewed non-PDF changes without automatic materialization;
+- a bounded resolver for a compatible external Career Core runtime;
+- no bundled native binary, telemetry, vacancy URL fetching, automatic document overwrite, or hidden provider call.
 
-Commands call the same package-owned runtime directly through bounded argv/stdin execution; they never call an LLM-facing tool, provider, model, network, PATH, Cargo, sibling checkout, or downloaded runtime. The workflow scans only explicitly configured `.md`/`.txt` roots, excludes assisted variants and inputs over 50,000 Unicode scalar values from authoritative operations, and never overwrites source files. See [`docs/design.md`](docs/design.md), [`docs/product-flow.md`](docs/product-flow.md), and [`SECURITY.md`](SECURITY.md).
+Career Core remains authoritative for scores, evidence, warnings, uncertainty, matching, and proposal review. `pi-career` owns the Pi workflow and presentation layer; it does not reimplement Career Core algorithms or schemas.
 
-## Supported runtime targets
+> **Version note:** this README describes the `pi-career@0.3.0` candidate. Published `pi-career@0.2.0` is the prior native-free release, and `pi-career@0.1.0` is the historical bundled-runtime release. Until `0.3.0` is explicitly released and visible on the npm registry, use a reviewed local checkout or pinned Git commit.
 
-| Package target | Native platform |
-|---|---|
-| `darwin-arm64` | macOS on Apple silicon |
-| `linux-x64-gnu` | Linux x64 with glibc |
-
-Windows, macOS x64, Linux arm64, Linux musl, and unknown libc/platform combinations are unsupported. The package may register on an unsupported target, but deterministic operations fail closed with a payload-free `unsupported_platform` error; they never guess, download a runtime, search `PATH`, or invoke Cargo.
-
-The unsigned package-owned runtime artifacts were produced and natively verified from Career Core commit `a3cdb4c6d7f966397e93ea4664071975bca7228c` by [artifact run 30953471793](https://github.com/revazi/career-core/actions/runs/30953471793). [`runtime/manifest.json`](runtime/manifest.json) pins target paths, sizes, SHA-256 values, provenance, and bounded contract digests. Before the first bundled spawn in each process, the selected regular executable is checked for exact size, mode, and SHA-256; only successful verification is cached in memory.
-
-`CAREER_CLI_PATH` remains an optional developer/recovery override. When set, it must be a bounded absolute path to a separately reviewed compatible executable and takes precedence over the bundled runtime. Normal users do not set it.
-
-## End-user prerequisites
+## Requirements
 
+- Node.js 22.19 or newer
 - Pi with 0.84.0-compatible package APIs
-- one of the two supported native targets above
-- a reviewed clean local checkout, public Git commit, or exact npm version of this package
+- macOS or Linux on ARM64/x64; GNU Linux requires glibc 2.35+, and musl Linux is supported
+- either a compatible local `career` executable or network access for first-use acquisition of exact `@revazi/career@0.2.0`
 
-No separate Career Core checkout, `career` installation, Cargo, Rust toolchain, install-time build, or runtime download is required.
+Windows is unsupported. npm enforces the package `os` allowlist; for a local or Git registration, extension initialization fails with stable `unsupported_platform` guidance before registering any command or tool, inspecting `CAREER_CLI_PATH`, searching `PATH`, validating package routes, acquiring npm content, or opening private stdin.
 
-## Reviewed local installation
+## Install
 
-Pi local-path packages are referenced in place rather than copied. Register a reviewed clean checkout at a stable absolute path:
+After the registry confirms the release, install the exact version:
 
 ```bash
-cd /absolute/path/to/pi-career
-package_root="$(pwd -P)"
-pi install "$package_root"
+pi install npm:pi-career@0.3.0
 pi list
 ```
 
-Restart Pi or run `/reload` after a reviewed update. A local registration follows files at that path and does not pin future changes, so update the checkout only to reviewed revisions.
-
-Remove the registration with the same resolved path:
+For release-candidate testing, a clean checkout includes reproducible `dist/index.js` and `dist/pdf-worker.js` bundles, so local installation does not require a build or npm install:
 
 ```bash
 cd /absolute/path/to/pi-career
-package_root="$(pwd -P)"
-pi remove "$package_root"
+pi install "$(pwd -P)"
 pi list
 ```
 
-## Public npm installation pinned to a version
+Local-path installation loads the checkout in place. After a reviewed update, restart Pi or run `/reload`.
 
-After reviewing the release metadata, install an exact published version:
+To pin a reviewed Git commit instead:
 
 ```bash
-pi install npm:pi-career@0.1.0
-pi list
+pi install git:github.com/revazi/pi-career@<reviewed-full-commit>
 ```
 
-A versioned npm package is pinned and skipped by package updates. Review and install a new exact version to update. Remove it by package identity:
+Remove the exact source you installed:
 
 ```bash
 pi remove npm:pi-career
+
+# Or, for a local-path registration:
+cd /absolute/path/to/pi-career
+pi remove "$(pwd -P)"
 ```
 
-## Public Git installation pinned to a commit
+Developers who modify `src/` must rebuild the tracked bundles with `npm run build`; see [Development](#development).
+
+## Recommended first run
+
+The optimal path starts with deterministic analysis. The model-assisted path begins only if you review and submit the prompt prepared by `/career-workbench`.
+
+```mermaid
+flowchart TD
+    A["Start Pi"] --> B{"Persist this Pi session?"}
+    B -->|No| C["Start with pi --no-session"]
+    B -->|Yes| D["Use a normal session<br/>approve local persistence if prompted"]
+
+    C --> E["/career-setup<br/>add an original-resume root"]
+    D --> E
+    E --> F["/career-library<br/>review indexed originals and notices"]
+    F --> G["/career-analyze<br/>establish the deterministic baseline"]
+
+    G --> H{"Matching a vacancy?"}
+    H -->|No| I{"Want model-assisted help?"}
+    H -->|Yes| J["/new<br/>one fresh session per company and role"]
+    J --> K["/career-application<br/>create company/role context"]
+    K --> L["/career-vacancy<br/>paste text; Career Core validates it"]
+    L --> M["/career-match<br/>rank eligible original resumes"]
+    M --> I
+
+    I -->|No| N["Inspect deterministic details and stop"]
+    I -->|Yes| O["/career-workbench<br/>private prompt is prepared in the editor<br/>nothing is sent"]
+    O --> P{"Review and submit the prompt?"}
+    P -->|No| Q["Edit or cancel"]
+    P -->|Yes| R["Selected Pi model/provider<br/>uses career_run handles"]
+    R --> S["career_run reruns the complete<br/>deterministic baseline"]
+    S --> T{"Requested workflow"}
+    T -->|Explain score| U["Explain the complete deterministic result"]
+    T -->|Plan / rewrite / replacements| V["Career Core reviews external<br/>suggestions or replacements once"]
+    V --> W["Present retained items, discards, and warnings<br/>no automatic application or save"]
+    T -->|Tailor to vacancy| X["Analyze and match the original<br/>Career Core reviews variant changes once"]
+    X --> Y{"Original format"}
+    Y -->|PDF| AA["Return targeted manual changes only"]
+    Y -->|Markdown/text| AB["career_run ends the review turn"]
+    AB --> AD["/career-review<br/>inspect notices and exact changes<br/>all IDs start excluded"]
+    AD --> AE{"Review and submit selected IDs?"}
+    AE -->|No| Z
+    AE -->|Yes| AC["Later turn: career_run materialize<br/>assisted text remains in memory"]
+    AC --> AF{"Save this local variant?"}
+    AF -->|No| Z
+    AF -->|Yes| AG["/career-save<br/>review exact files and destination<br/>then confirm separately"]
+
+    N --> Z["Original remains unchanged<br/>assisted output is non-authoritative<br/>and is never reranked as an original"]
+    Q --> Z
+    U --> Z
+    W --> Z
+    AA --> Z
+    AG --> Z
+```
 
-After reviewing a full commit SHA, install directly from this public repository; no configured Git credentials are required:
+### 1. Start with a transient Pi session
+
+For a first test—or whenever you do not want Pi to write this conversation to a session JSONL—start:
 
 ```bash
-pi install git:github.com/revazi/pi-career@<full-reviewed-commit-sha>
-pi list
+pi --no-session
 ```
 
-A pinned Git package is not moved by `pi update --extensions`. To update, review a new full SHA and install that explicit ref:
+This prevents Pi session persistence for the new run. It is not secure erasure and does not remove shell history, previous sessions, backups, provider copies, or npm cache data.
 
-```bash
-pi install git:github.com/revazi/pi-career@<new-full-reviewed-commit-sha>
+If you use a normal persisted session, `pi-career` asks for explicit consent before it adds private vacancy/workflow state. A local-session decision is separate from permission to send content to a model provider.
+
+### 2. Configure an originals library
+
+Put one or more original resumes in a dedicated directory. Supported inputs are:
+
+- UTF-8 Markdown (`.md`)
+- UTF-8 plain text (`.txt`)
+- searchable, unencrypted PDF (`.pdf`), up to 10 MiB and 20 pages
+
+Image-only/scanned PDFs need OCR or export to Markdown/text first. DOCX, Pages, vacancy URLs, and OCR are not supported.
+
+In Pi, run:
+
+```text
+/career-setup
+```
+
+Choose **Add root** and enter the resume directory. Setup stores the canonical root in private local Pi configuration; it does not copy, move, or edit your resumes.
+
+Setup also displays a preferred `variants/` destination. This is suggestion-only: it creates no directory or file and does not authorize a save.
+
+### 3. Confirm what was indexed
+
+```text
+/career-library
+```
+
+Review the indexed originals and any notices. Fix unreadable, oversized, invalid UTF-8, encrypted, or image-only documents before continuing.
+
+### 4. Analyze an original before tailoring it
+
+```text
+/career-analyze
+```
+
+Choose one original resume. The command runs deterministic readiness analysis, shows a compact card, and lets you inspect the complete result or focused sections in a transient viewer.
+
+This is the best first baseline: understand the resume on its own before adding vacancy-specific concerns.
+
+### 5. Use one Pi session per company and role
+
+Start a fresh Pi conversation before each application:
+
+```text
+/new
+/career-application
+```
+
+Enter the company and role. The application context scopes its vacancy and result cards and names an otherwise unnamed Pi session. It does not create an application directory or write career documents.
+
+Then set the vacancy:
+
+```text
+/career-vacancy
+```
+
+Paste the vacancy text directly. `pi-career` never fetches a vacancy URL. Career Core validates the text before it becomes the current vacancy.
+
+### 6. Match your originals
+
+```text
+/career-match
+```
+
+Choose all eligible originals or a subset. The command deterministically normalizes the vacancy, analyzes each selected original, matches each original to the vacancy, and then ranks the results conservatively. You can open detailed evidence for a selected row.
+
+Scores and recommendations are bounded workflow guidance—not hiring predictions, ATS guarantees, or evidence that an employer will respond.
+
+### 7. Open the workbench only when you want model-assisted help
+
+```text
+/career-workbench
+```
+
+Choose an original and a guided mode. The command prepares a private prompt in Pi's normal editor; it does **not** invoke Career Core or a model and sends nothing automatically. Read the prompt and source payload before submitting it.
+
+After you submit, the selected Pi agent uses `career_run` to rerun complete deterministic baselines and Core-review any proposed suggestions, replacements, or vacancy-specific changes. The original remains immutable.
+
+For a non-PDF tailored variation, `career_run variant-review` ends the agent turn. Run `/career-review <review-handle>` to inspect every warning/discard and each exact before/after/evidence record; all retained changes start excluded. Explicitly include the IDs you want, review those selected changes together, and separately confirm the handle/ID-only editor handoff before submitting it as a later turn. The selector never materializes or submits automatically. After successful materialization, you may separately run `/career-save <variant-handle>` to inspect the complete local file plan and confirm it; the model cannot invoke saving. For PDFs, the workbench returns targeted manual changes only because extracted text cannot preserve typography, columns, spacing, or graphics; PDF review handles cannot enter selection, materialization, or saving.
+
+## Slash command reference
+
+The workflow commands below require interactive TUI/RPC mode except `/career-vacancy clear`; `/career-review` is TUI-only, `/career-save` supports TUI/RPC, and `/career-tools` is a lightweight tool-surface switch. Slash-command handlers do not invoke a model/provider. `/career-workbench` and `/career-review` prepare editor prompts whose later user submission does. Core-backed commands may resolve or acquire the external runtime before processing private input.
+
+### `/career-setup [status]`
+
+Configure and inspect package-level resume-library settings.
+
+Without arguments, the setup menu can:
+
+- add a readable resume root;
+- rescan configured roots;
+- show setup and scan status;
+- set or clear a suggestion-only resume-variation directory.
+
+It stores only canonical root paths, bounded labels, and the optional variation-directory suggestion. It does not install Career Core, create the suggested directory, copy resumes, or write result files.
+
+Use `/career-setup status` to display the current summary and notices without opening the menu.
+
+### `/career-library [status]`
+
+Browse and maintain the configured resume index.
+
+The menu can:
+
+- browse indexed PDF, Markdown, and text records;
+- add or remove a root from configuration;
+- rescan all configured roots;
+- show counts and actionable scan notices.
+
+Removing a root changes configuration only; it never deletes files. Assisted variants with valid sidecars remain visible but are excluded from authoritative analysis and matching. Oversized originals remain visible as unavailable where appropriate.
+
+Use `/career-library status` for a summary without the menu.
+
+### `/career-application [status|clear]`
+
+Create and manage one company/role context for the current Pi session.
+
+A new application records bounded company and role labels, starts at `preparing`, and can later be marked `applied`, `interviewing`, or `closed`. Its immutable application ID scopes the current vacancy and result cards. If the Pi session has no name, the command names it from the company and role.
+
+Use:
+
+- `/career-application status` to show the active context;
+- `/career-application clear` to clear the application and its current vacancy.
+
+After clearing—or before working on another company/role—run `/new`. The same Pi session cannot be reused for a second application context because earlier private prompts would still be in that conversation.
+
+This command manages session state only. It does not create workspace folders or application files.
+
+### `/career-vacancy [clear]`
+
+Set, inspect, replace, or clear the current vacancy.
+
+When no vacancy exists, the command opens an editor for pasted text. When one exists, it offers **Replace**, **View**, **Clear**, or **Cancel**. New or replacement text is normalized and validated by Career Core before being stored in workflow state.
+
+The vacancy is bound to the active application when one exists. It must be supplied as text; URLs are never fetched.
+
+Use `/career-vacancy clear` to clear it directly. This is the only career slash-command action allowed without interactive TUI/RPC mode.
+
+### `/career-analyze [filter]`
+
+Run deterministic readiness analysis for one eligible original resume.
+
+The optional filter is a case-insensitive substring matched against the resume label, relative path, and stable ID. For example:
+
+```text
+/career-analyze backend
 ```
 
-Remove it by repository identity:
+After selecting a resume, the command:
+
+1. requests persistence consent when needed;
+2. runs the authoritative original-resume analysis;
+3. stores only a bounded result card in session state;
+4. offers complete/focused transient detail;
+5. can prepare a single-resume match command when a vacancy exists;
+6. can open the guided workbench for the selected resume.
+
+It never analyzes an assisted variant as an original. Oversized output fails without partial results or hidden file export.
+
+### `/career-match [filter]`
+
+Deterministically rank eligible original resumes against the current vacancy.
+
+Set a vacancy first with `/career-vacancy`. The optional filter uses the same label/relative-path/ID substring matching as `/career-analyze`.
+
+The command lets you choose every matching original or select a subset. It then runs, sequentially:
+
+1. vacancy normalization;
+2. readiness analysis for every selected original;
+3. original-resume/vacancy matching for every selected original;
+4. stable conservative ranking and tie display.
+
+The summary keeps unavailable oversized results visible instead of silently dropping them. Select a ranked row to inspect scores, strengths, gaps, confidence, warnings, evidence, and vacancy context.
+
+Assisted variants are never accepted as authoritative match inputs.
+
+### `/career-workbench [filter]`
+
+Prepare a visible, guided prompt for the selected Pi agent.
+
+The optional resume filter behaves like `/career-analyze`. Available modes are:
+
+- **Explain my score** — rerun and explain the complete deterministic analysis;
+- **Create a reviewed improvement plan** — propose at most three advisory suggestions and Core-review them once;
+- **Guided rewrite interview** — ask a small set of factual questions first, wait for your answers, then review bounded exact replacements in a later turn;
+- **Draft reviewed replacements** — propose and Core-review bounded before/after replacements without claiming they were applied;
+- **Create a tailored variation** — available when a current vacancy exists; analyze and match the original, then review vacancy-grounded changes;
+- **Ask my own question** — prepare a custom resume-only request under the same safety rules.
+
+The command itself calls neither Career Core nor a provider. It puts the complete selected resume—and the vacancy only for tailoring—into Pi's editor. Nothing is sent until you submit. Submitting may persist that message and send it to the provider selected in Pi.
+
+The workbench and model never save automatically. Only a later successful non-PDF materialization can be passed by the user to `/career-save` for separate exact local preview and confirmation.
+
+### `/career-review <review-handle>`
+
+Review and explicitly select retained changes from a current non-PDF `career_run variant-review` result. This command is available only in TUI mode and only while the ephemeral review handle remains in the current process/session branch.
+
+The bounded selector:
+
+- requires inspection/acknowledgment of all Core warnings and discarded-change reasons;
+- shows every canonical change as excluded by default;
+- opens a paged exact view of its before text, proposed after text, line bounds, resume evidence, and vacancy evidence;
+- includes a change only after you toggle it from that exact view;
+- requires at least one included canonical ID before continuing;
+- pages all selected exact changes together in a compact labeled view, lets you reopen any selected record directly, and requires a separate final prepare choice with a back option for revisions.
+
+Only that final prepare choice creates a short editor message containing the review handle and selected IDs. It does not invoke Career Core, materialize a result, contact a provider, append selection state to the Pi session, save a result, or write a file. Review and submit that editor message manually to start the later materialization turn. Escape cancels without preparing anything.
+
+PDF review changes remain manual-application guidance and are rejected by `/career-review`, `career_run materialize`, and `/career-save`.
+
+### `/career-save <variant-handle>`
+
+Save one current successful Markdown/text `career_run materialize` result as a new assisted local variant. This user-only command is not a model tool and is available in TUI/RPC mode on supported POSIX systems.
+
+Before writing anything, it:
+
+1. revalidates the ephemeral variant and unchanged original;
+2. derives an eligible direct-child managed variants directory;
+3. opens a complete canonical preview containing exact destination paths, artifact/sidecar bytes, hashes, and any directory marker;
+4. requires the preview to be returned byte-identically;
+5. asks for a separate final confirmation.
+
+It then publishes new `0600` files in a `0700` managed directory without replacing existing paths, writes a strict assisted/non-authoritative sidecar, and rescans before reporting success. Missing, malformed, edited, or hash-mismatched assisted metadata is quarantined and never falls back to original eligibility. Saving invokes no Career Core operation, provider, model, network request, or session entry. PDF handles fail closed; the save workflow is supported on pi-career's macOS/Linux platforms with its POSIX-private filesystem contract.
+
+Saved files are not securely erased by session deletion, root removal, package removal, or `PI_OFFLINE=1`. Pi-career never automatically overwrites, updates, moves, or deletes them.
+
+### `/career-tools [managed|raw|status]`
+
+Control which Career tools are active in model context.
+
+- `/career-tools managed` keeps only the compact `career_run` workflow active. This is the default and recommended mode.
+- `/career-tools raw` also activates `career_core_discover`, `career_core_resume`, and `career_core_job` for explicit schema/debugging work.
+- `/career-tools status` reports the current tool mode.
+
+This command changes only the active model-tool surface. It does not change slash-command behavior, runtime resolution, privacy boundaries, or compatibility validation.
+
+## Managed agent workflow
+
+Normal users do not need to call raw JSON tools. The package's Agent Skill instructs Pi to use `career_run`:
+
+1. `context` obtains ephemeral handles for eligible originals and the current vacancy;
+2. `analyze` and `match` return compact projections backed by complete in-memory Core results;
+3. suggestion, replacement, and variant proposals must pass the corresponding Core review command;
+4. `detail` hydrates only the requested evidence, warning, check, change, document, or raw section;
+5. non-PDF `variant-review` ends its turn so `/career-review` can collect an explicit local selection and prepare a later user message;
+6. `materialize` requires that unchanged review handle and exactly the user-selected retained IDs;
+7. only the user may separately run `/career-save <variant-handle>` for unchanged preview and confirmation.
+
+Handles and complete results remain bounded in process memory and disappear on session/branch replacement, reload, or shutdown. They are not result files and cannot be reconstructed safely from chat text.
+
+The raw tools are retained for advanced compatibility work only:
+
+- `career_core_discover`
+- `career_core_resume`
+- `career_core_job`
+
+When raw mode is explicitly enabled, discovery-first use remains mandatory: capabilities → operations → schema list/export/bundle → exact JSON input.
+
+## External Career Core runtime
+
+`pi-career` contains no native Career Core binary. A Core-backed command resolves a compatible runtime in this fixed order:
+
+1. absolute `CAREER_CLI_PATH`;
+2. `career` on `PATH`;
+3. package-local exact `@revazi/career@0.2.0`;
+4. bounded acquisition of exact `@revazi/career@0.2.0` from the canonical npm registry.
+
+Runtime installation is separate from loading the local Pi package. `/career-setup`, `/career-library`, `/career-application`, `/career-workbench`, and `/career-review` itself do not resolve or invoke Core; `/career-review` requires a still-live review produced earlier by `career_run`. `/career-vacancy`, `/career-analyze`, `/career-match`, `career_run`, and the raw tools do need Core.
+
+Extension initialization requires macOS or Linux and fails unsupported platforms with one payload-free `unsupported_platform` error before registering any command/tool or doing route work. Before private document stdin opens on a supported platform, the selected executable must pass the exact managed Career Core 0.2.0 operation and schema compatibility checks. An invalid explicit `CAREER_CLI_PATH` fails without fallback.
+
+The pi-career runtime target matrix is:
+
+| Operating system | Architecture | Runtime target | Requirement |
+| --- | --- | --- | --- |
+| macOS | ARM64 | `darwin-arm64` | native Apple silicon |
+| macOS | x64 | `darwin-x64` | native Intel |
+| GNU/Linux | x64 | `linux-x64-gnu` | glibc 2.35+ |
+| GNU/Linux | ARM64 | `linux-arm64-gnu` | glibc 2.35+ |
+| musl Linux | x64 | `linux-x64-musl` | detected musl runtime |
+| musl Linux | ARM64 | `linux-arm64-musl` | detected musl runtime |
+
+The platform-specific optional packages are internal launcher details; install or acquire only exact `@revazi/career@0.2.0`. Pi-career validates the launcher's exact ordered six-package v2 manifest and lockstep versions before direct execution, while the launcher remains authoritative for native selection and integrity. Windows remains unsupported.
+
+To prohibit acquisition:
 
 ```bash
-pi remove git:github.com/revazi/pi-career
+PI_OFFLINE=1 pi --no-session
 ```
 
-Version `0.1.0` is published as the public npm package `pi-career` with no lifecycle scripts, package-owned runtime npm dependencies, or bundled Pi peer contents. The npm tarball carries the same two unsigned, hash-verified, not-notarized native executables as reviewed local and Git installations; it does not build them with Cargo on the user's machine.
+Offline Core-backed use then requires a compatible `CAREER_CLI_PATH`, `career` on `PATH`, or package-local launcher. Acquisition receives no resume or vacancy input, but it may leave ordinary npm cache or `_npx` data; this is not secure erasure.
+
+## Privacy and persistence
+
+Use `pi --no-session` when you do not want a new Pi session JSONL. In a persisted session, review the package's consent prompt before continuing with private content.
+
+Possible persistence surfaces are distinct:
+
+- **Package config:** canonical resume-root paths, bounded labels, and an optional variation-directory suggestion; never resume text, vacancy text, or full Core output.
+- **Pi session:** consent, application/vacancy workflow entries, bounded result cards, and potentially tool arguments/results or submitted workbench messages.
+- **Model provider:** only content you submit through ordinary Pi model interaction; `/career-workbench` makes the private payload visible before submission, while `/career-review` prepares only an ephemeral handle and selected canonical IDs.
+- **Approved local variant files:** exact assisted Markdown/text bytes plus bounded marker/sidecar metadata only after `/career-save` preview and confirmation; never full Core JSON.
+- **npm cache:** ordinary package-acquisition data, never private Career Core stdin.
 
-The `v0.1.0` release consists of the exact npm version, an unsigned annotated Git tag, and a GitHub Release; the reviewed full commit SHA and exact npm version are the installation coordinates. There is no crate publication, custom release asset, signing, or notarization. Both the package-owned production audit and complete development/host-Pi audit are clean at the explicit low threshold. Native-license evidence received documented sole-maintainer review, not independent legal review; see [`docs/releasing.md`](docs/releasing.md).
+`pi-career` does not create payload/result temporary files, export full Core JSON, overwrite originals, or automatically save assisted resumes. Explicit `/career-save` files are local, private-mode, assisted/non-authoritative, and excluded from analysis/matching. Searchable PDF extraction is local, bounded, and network-disabled.
 
-## Contributor build and verification
+See [`SECURITY.md`](SECURITY.md), [`docs/design.md`](docs/design.md), and [`docs/product-flow.md`](docs/product-flow.md) for the complete boundary and threat model.
 
-Node.js 22.19 or newer is required for development checks; release verification uses npm 10.9.3 from the Node 22.19 CI toolchain. TypeScript under `src/` is authoritative. `dist/index.js` is its reproducible generated bundle and is intentionally tracked with the reviewed native runtimes so clean local, public-Git, and npm packages load without development dependencies. Node build/test tooling stays as directly executed `.mjs` under `scripts/` and `tests/` and is excluded from the package artifact. Pi-provided packages remain external peers.
+## Current limitations
+
+- Supported original formats: searchable PDF, Markdown, and UTF-8 text.
+- No OCR, DOCX/Pages editing, vacancy URL fetching, or PDF layout reconstruction.
+- No automatic resume or application-workspace saving; explicit materialized-variant saving is private Markdown/text only on supported macOS/Linux filesystems.
+- PDF workbench output is targeted manual guidance only.
+- Assisted variants remain non-authoritative and cannot be reranked as originals.
+- Matching is conservative workflow guidance, not a hiring prediction or proprietary ATS simulation.
+- Supported runtime targets are `darwin-arm64`, `darwin-x64`, `linux-x64-gnu`, `linux-arm64-gnu`, `linux-x64-musl`, and `linux-arm64-musl`; Windows is unsupported.
+
+The future application-workspace contract is documented in [`docs/application-workspaces.md`](docs/application-workspaces.md); those filesystem-writing phases are not implemented.
+
+## Development
+
+TypeScript under `src/` is authoritative. `dist/index.js` and `dist/pdf-worker.js` are reproducible tracked bundles for clean local and Git loading.
 
 ```bash
 npm ci
 npm run build
-git diff --exit-code -- dist/index.js
+git diff --exit-code -- dist/index.js dist/pdf-worker.js
+npm run bench:tokens
+npm run bench:tokens:compare
 npm run check
-npm run test:bundled-runtime
+npm run test:runtime-resolution
+npm run test:career-package
 npm run audit:production
 npm run audit:full
 npm run check:publish
 PI_OFFLINE=1 npm run test:pi-smoke
 PI_OFFLINE=1 npm run test:install
+npm run test:compat
 git diff --check
 ```
 
-`npm run build` rebuilds only `dist/index.js`; it never builds or downloads native runtimes. `npm run check:runtime-artifacts` enforces the runtime manifest, provenance, five-file source artifact contract, target magic, exact hashes/sizes/modes, and package bounds. `npm run audit:production` requires zero package-owned production vulnerabilities and `npm run audit:full` requires zero vulnerabilities across the complete development/host-Pi tree, both from an explicit low-severity threshold. Production/full audit and package commands invoke `process.execPath` with the absolute npm CLI derived from that real Node installation, verify any inherited `npm_execpath`, and remove omit/include/audit-level/`NODE_ENV` overrides; npm and tar are never selected from `PATH`. `npm run check:publish` is a direct Node authoritative readiness orchestrator but does not publish anything: it runs both strict audits and the package checks. Strict bounded parsing rejects duplicate decoded keys in audit and pack JSON. The package check uses verified absolute `/usr/bin/tar`, proves the tarball has no `node_modules` or Pi package contents, keeps exactly `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, and `typebox` as wildcard external peers, extracts the artifact, loads it, executes the bundled runtime, and performs an isolated install/list/remove smoke. Any future audit finding blocks publication and requires remediation rather than a checked-in acceptance baseline.
+`npm run bench:tokens` collects the current synthetic model-visible surfaces, including Pi's stable always-visible Skill name/description metadata and the complete on-demand `career-core` Skill for matching career tasks. Linked Skill references and machine-specific discovery paths stay outside that boundary. `npm run bench:tokens:compare` verifies the surface digest, immutable `c7d7634…` before and `7ed36c4…` after source/Skill trees and frozen bytes from Git history, exact frozen before/after deltas, managed serialization parity, semantic/privacy invariants, budgets, and no current workflow regression relative to the frozen after evidence. Later source may differ and improve without rewriting that historical snapshot. The finalized frozen evidence records 25,652 → 21,552 aggregate workflow tokens (15.98% reduction) with no workflow regression.
 
-Optional local compatibility uses an explicitly supplied reviewed Career Core fixture root while still executing the bundled runtime:
+`npm run test:career-package` is the network-capable exact-package integration test. `npm run test:compat` skips unless an explicitly reviewed fixture checkout is provided:
 
 ```bash
 CAREER_CORE_FIXTURE_ROOT=/absolute/path/to/reviewed/career-core \
   npm run test:compat
 ```
 
-Hosted CI needs no separate Core checkout or provider credentials. Its native matrix executes every claimed target: Ubuntu x64 GNU and macOS arm64.
-
-## Privacy before document operations
+`npm run build` rebuilds JavaScript bundles only; it never builds or downloads native runtimes. `npm run check:publish` verifies readiness and package contents but does not publish anything.
 
-Pi may persist native-tool arguments/results and workflow custom entries in session JSONL. The slash commands require the displayed session-persistence decision before the first private vacancy or compact result card is appended to a persisted session. Global config stores only canonical resume-root paths and bounded labels—never resume text, vacancy text, or Core output. Full Core JSON is not stored by the workflow, and custom workflow entries are excluded from LLM context.
+## Security and release provenance
 
-For direct native-tool use, make the same explicit persistence decision before placing private resume or job content in `input_json`. Prefer a new transient run when session saving is not wanted:
-
-```bash
-pi --no-session
-```
+The exact reviewed external runtime coordinate is [`@revazi/career@0.2.0`](https://www.npmjs.com/package/@revazi/career/v/0.2.0), published from Career Core commit [`536690632884c17336cc3c108f1bba0f254b862b`](https://github.com/revazi/career-core/tree/536690632884c17336cc3c108f1bba0f254b862b). Its launcher owns native target/libc selection and package metadata, provenance, file invariants, size, format, and SHA-256 verification. Registry integrity and SLSA v1 provenance were reviewed for the user-facing launcher and all six lockstep native packages. Pi-career validates that exact six-package v2 manifest and supports only its macOS/Linux targets.
 
-This is not a secure-erasure guarantee and does not remove previous sessions, shell history, backups, provider copies, or saved output. Local Pi-context approval also does not authorize sending content to an external model/provider.
+Historical published `pi-career` v0.1.0 coordinates are retained for verification:
 
-Start with `career_core_discover`, invoke only capabilities reported as available, and export the exact input schema before document calls. If the adapter reports `result_too_large` or `result_too_many_lines`, do not request or use partial output. Full-result export is not yet available through pi-career.
+- npm: [`pi-career@0.1.0`](https://www.npmjs.com/package/pi-career/v/0.1.0)
+- Git commit: [`967da62503bc8a97c070946f6506ea3471baeb34`](https://github.com/revazi/pi-career/tree/967da62503bc8a97c070946f6506ea3471baeb34)
+- npm integrity: `sha512-mmbDdWDyWz77f2uLzZECJT9E6w1ZRCJjYFrUnZd3ldoS6ehEa5DrCENIfavHR5xMOFi0of6AVQ35ZTxwpeDeAQ==`
+- GitHub Release: [`v0.1.0`](https://github.com/revazi/pi-career/releases/tag/v0.1.0)
 
-## Maintainer and support
+That historical release bundled native artifacts; `pi-career@0.2.0` and later do not. Historical evidence remains in [`docs/native-dependency-inventory.md`](docs/native-dependency-inventory.md), [`docs/releasing.md`](docs/releasing.md), and [`docs/licenses/`](docs/licenses/).
 
-Maintained by [Revaz Zakalashvili](https://github.com/revazi). Use this repository's Issues for sanitized bugs and scoped feature requests, follow [`CONTRIBUTING.md`](CONTRIBUTING.md) for changes, and follow [`SECURITY.md`](SECURITY.md) for vulnerabilities. Never place private career content or vulnerability details in an ordinary issue.
+Use [Issues](https://github.com/revazi/pi-career/issues) only for sanitized bugs and scoped feature requests. Follow [`SECURITY.md`](SECURITY.md) for private vulnerability reports. Never attach real resumes, vacancies, credentials, provider responses, or Pi session files to a public issue.
 
 ## License and provenance
 
-Licensed under either Apache-2.0 or MIT, at your option. See [`LICENSE-APACHE`](LICENSE-APACHE), [`LICENSE-MIT`](LICENSE-MIT), [`NOTICE`](NOTICE), and the package-bounded runtime license/notices files under [`runtime/`](runtime/).
+Licensed under either Apache-2.0 or MIT, at your option. See [`LICENSE-APACHE`](LICENSE-APACHE), [`LICENSE-MIT`](LICENSE-MIT), and [`NOTICE`](NOTICE).
 
-The locked normal/build dependency evidence for both native CLI targets is in [`docs/native-dependency-inventory.md`](docs/native-dependency-inventory.md). The package preserves the exact selected MIT/copyright texts for every reachable crate group, Rust 1.97.1 Standard Library evidence, and the required [`Unicode License V3`](docs/licenses/Unicode-3.0.txt) text under [`docs/licenses/`](docs/licenses/). `npm run check:native-licenses` enforces that payload. The inventory is evidence, not legal advice or automated release approval; [`docs/releasing.md`](docs/releasing.md) requires documented human sign-off and transparently records sole-maintainer review when independent review is unavailable.
+The external `@revazi/career` distribution carries its own native licenses and notices.