pi-career 0.2.0 → 0.3.0

package/docs/application-workspaces.md

@@ -6,7 +6,7 @@ A single active vacancy on a Pi session branch is not enough to organize a real
 
 This document defines the target workspace contract. The current package does not create these private files yet; that requires a separately reviewed, explicit persistence workflow.
 
-The current `/career-setup` preferred resume-variation directory is narrower and suggestion-only. It gives the selected Pi agent a primary destination to recommend after a separate user request, defaults to `variants/` under the selected original's configured root, and creates nothing. It is not the future application workspace root and does not relax the persistence requirements below.
+The current `/career-setup` preferred resume-variation directory is narrower and suggestion-only. It gives the selected Pi agent a primary destination to recommend after a separate user request, defaults to `variants/` under the selected original's configured root, and creates nothing. The user-only [`variant-save-workflow.md`](variant-save-workflow.md) can save one current in-memory Markdown/text materialization there only after exact file-specific approval. It does not establish an application workspace root and does not relax the persistence requirements below.
 
 ## Directory model
 
@@ -63,7 +63,7 @@ Original resumes are immutable:
 - Never overwrite, rename, move, or reformat an original automatically.
 - A PDF workbench has extracted text only. It cannot inspect or preserve typography, columns, spacing, graphics, or other visual layout.
 - Current PDF workbench output is limited to reviewed change guidance and bounded before/after snippets for manual application; pi-career does not save a PDF change plan.
-- Current Markdown/text materialization can return assisted text in process memory after user selection. A future save phase may write that text to a new file only under the approval and sidecar rules below.
+- Current Markdown/text materialization returns assisted text in process memory after user selection. `/career-save` may write that exact text to a new local variant only under its separate preview, approval, no-clobber, and sidecar rules.
 - DOCX/Pages/other styled-source mutation remains unsupported until format-specific fidelity and safety are designed and tested.
 - Every generated resume file is assisted/non-authoritative, has a valid sidecar, and is excluded from authoritative readiness analysis and job matching.
 
@@ -92,7 +92,7 @@ The current application workflow binds only:
 - the current vacancy;
 - bounded deterministic analysis/match cards.
 
-Selected-original handles, complete Core results, exact review inputs, and materialized text remain process-memory-only. A submitted workbench message may persist as an ordinary Pi conversation entry, but pi-career does not store it as application workspace state. Assisted artifact references are not implemented yet.
+Selected-original handles, complete Core results, exact review inputs, and live reviewed-change selections remain process-memory-only. Materialized text also remains in memory unless the user separately approves `/career-save`; the saved artifact and sidecar are local files, not application workspace state or Pi session entries. Assisted application-workspace references are not implemented yet.
 
 A persisted Pi session can still contain private prompts and tool arguments. Application-file approval is separate from Pi session persistence and separate from provider disclosure. The workflow must ask before the first private workspace write and show the exact workspace path and files to be created.
 
@@ -108,7 +108,7 @@ This sequence extends the current in-session flow; steps involving an applicatio
 4. `/career-match` ranks eligible originals and records the selected original reference.
 5. `/career-workbench` prepares a visible guided editor prompt that reruns complete deterministic baselines after submission; its rewrite interview can ask one bounded batch of factual questions and wait for a later answer.
 6. External suggestions, replacements, or vacancy-specific variant changes use exact verbatim source targets and are reviewed once by exact Career Core schemas; discarded proposals are reported rather than automatically repaired or retried.
-7. For a non-PDF variant, the first assisted turn stops so the user can explicitly select canonical retained change IDs; only a later turn materializes those exact selections.
+7. For a non-PDF variant, the first assisted turn terminates after review. `/career-review` defaults all changes to excluded, pages exact warnings/discards and before/after/evidence, and prepares only the explicitly selected IDs for a later user-submitted materialization turn.
 8. A future save action separately requests local-file approval, previews exact new files, and writes only inside the selected application directory.
 9. Originals remain unchanged, and assisted variants remain excluded from authoritative reranking.
 
@@ -118,6 +118,7 @@ This sequence extends the current in-session flow; steps involving an applicatio
 
 - searchable PDF indexing and actionable notices
 - visible, bounded workbench editor handoff
+- bounded TUI reviewed-change selection and later handle/ID-only editor handoff
 - immutable-original and format-fidelity instructions
 - branch-aware application metadata in consented custom session entries
 - company/role/status selection and vacancy/result binding to application ID
@@ -131,7 +132,7 @@ This sequence extends the current in-session flow; steps involving an applicatio
 
 ### Phase C: explicit workspace persistence
 
-Requires separate review of:
+The narrower implemented materialized-variant save workflow does not complete Phase B or authorize Phase C. Application workspace persistence still requires separate review of:
 
 - config schema migration for an application workspace root
 - canonical containment and symlink/race protections

package/docs/career-run-roadmap.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Career Core Phase 8 was merged as `f6d1783` through PR #21. The first compact `career_run` implementation, ephemeral handles, complete bounded in-memory results, detail hydration, raw-tool activation control, and synthetic token benchmark are implemented here. Runtime distribution now belongs to reviewed exact `@revazi/career@0.1.1`; pi-career packages no native artifacts and resolves compatible external routes before managed execution. Package-owned save/export, richer interactive change selection/navigation, and broader PDF extraction compatibility remain later reviewed work.
+Career Core Phase 8 was merged as `f6d1783` through PR #21. The compact `career_run` implementation, ephemeral handles, complete bounded in-memory results, detail hydration, raw-tool activation control, synthetic token benchmark, and bounded non-PDF reviewed-change selector are implemented here. Runtime distribution now belongs to reviewed exact `@revazi/career@0.2.0`; pi-career packages no native artifacts, supports only macOS/Linux, and resolves compatible external routes before managed execution. Synthetic PDF compatibility covers reviewed Chromium-generated tagged and untagged documents, a reproducible ReportLab-generated two-page document, an embedded open-licensed font, a CSS multi-column layout, and fail-closed image-only/malformed/oversized inputs. The package-owned user-confirmed materialized-variant save workflow is implemented for private Markdown/text artifacts on those supported platforms. The dedicated token-optimization benchmark study now has frozen before/after evidence bound to the reviewed production commits and exact source/Skill trees. Full application workspaces, further review UX, and further PDF generator/font coverage remain later explicitly authorized work; Windows is unsupported rather than deferred roadmap scope.
 
 Completed sequence:
 
@@ -12,6 +12,9 @@ Completed sequence:
 4. Primary `career_run` implementation with raw tools inactive by default.
 5. Reproducible synthetic context benchmark and budget gates.
 6. External local-first resolver with exact package acquisition, pre-private-input compatibility validation, and removal of bundled native artifacts.
+7. Turn-terminating variant review plus bounded TUI warning/discard review, exact change inspection, explicit selection, and later editor handoff without automatic materialization.
+8. User-only TUI/RPC exact preview and confirmed no-clobber saving of current POSIX Markdown/text materializations with fail-closed assisted sidecars and rescanning.
+9. Versioned pre-optimization token benchmark with immutable Git source/Skill-tree and snapshot provenance, actual contracts and managed serialization parity, Skill discovery/full-load context, call/result/detail/editor surfaces, independent workflow rollups, semantic-retention invariants, and explicit before/optimizing/after gates.
 
 This document records findings and phase boundaries; it does not independently authorize persistence, publication, release, or later deferred work.
 
@@ -50,10 +53,10 @@ career_run {command: match, handle: resume:...}
 career_run {command: variant-review, handle: resume:..., payload: {changes: [...]}}
 career_run {command: materialize, handle: review:..., payload: {selected_change_ids: [...]}}
 career_run {command: detail, handle: result:..., payload: {section: evidence}}
-# package-owned save remains deferred
+# local saving is a separate user-only /career-save slash command
 ```
 
-This is the implemented compact v1 command shape; package-owned save remains deferred. Private document text continues to travel only through bounded stdin at the Career Core process boundary, never through CLI arguments.
+This is the implemented compact v1 model-tool shape; local saving remains outside it as the user-only `/career-save <variant-handle>` slash command. Private document text continues to travel only through bounded stdin at the Career Core process boundary, never through CLI arguments.
 
 Career Core remains authoritative for operations, schemas, algorithms, typed errors, evidence, warnings, uncertainty, ordering, deterministic baselines, and assisted/non-authoritative semantics. Pi-career owns handles, orchestration, projection, interaction, and explicitly approved persistence.
 
@@ -187,21 +190,24 @@ Common results include only the decision surface needed for the next action whil
 
 The complete Core result must be captured before projection, remain unchanged, and be recoverable in the current process. It must never be partially consumed after truncation. Resume/job payloads and full results must not be written to temp files without a separately approved design.
 
-### Deferred richer review rendering and selection
+### Delivered bounded reviewed-change selection
 
-A later reviewed phase may add bounded custom rendering for:
+For non-PDF variant reviews, `career_run variant-review` terminates the agent turn and returns the ephemeral review handle. `/career-review <review-handle>` then provides bounded TUI navigation over:
 
-- before/proposed-after changes
-- evidence and source targets
-- confirmed/provisional status
-- warnings and factuality limitations
-- discard codes
+- all warnings, factuality limitations, and discard records, which require explicit acknowledgment;
+- every canonical retained change, excluded by default;
+- exact before/proposed-after text, line bounds, resume evidence, and vacancy evidence in a paged view;
+- an explicit included-ID set in original Core order;
+- a final paged cross-change view with compact labels for every exact selected record;
+- direct final-stage reopening of any selected record, followed by a separate prepare-or-back decision.
 
-The initial managed adapter already requires explicit canonical change IDs and reuses the exact complete reviewed proposal for materialization; the model must not select automatically. A later bounded multi-select interaction may make that user decision easier without changing the authority boundary.
+Only the final prepare decision creates a later ordinary editor message containing the unchanged review handle and selected canonical IDs. It does not call Core, submit to a provider, append selection state, materialize, save, or write. The user must review and submit that message separately. Exact cached review input remains process-memory-only and deterministic materialization still reuses it unchanged. PDF review handles fail closed at selection and materialization because extracted text cannot preserve PDF styling.
+
+Further reviewed work may improve navigation or presentation further, but must retain the same warning, evidence, authority, cancellation, process-memory, cross-change confirmation, and explicit-selection boundaries.
 
 ### Approved save workflow
 
-A later explicitly authorized save action should require:
+The implemented design and threat model are recorded in [`variant-save-workflow.md`](variant-save-workflow.md). `/career-save` requires:
 
 1. exact destination and file preview
 2. explicit user confirmation
@@ -211,40 +217,44 @@ A later explicitly authorized save action should require:
 6. immutable originals and overwrite rejection
 7. immediate library rescan with variants excluded from authoritative analysis/matching
 
-Destination configuration remains suggestion-only until this phase is designed, threat-reviewed, implemented, and tested.
+Destination configuration remains suggestion-only until one exact `/career-save` plan is previewed unchanged and separately confirmed. Full-result export and application-workspace persistence remain outside this narrower materialized-variant save workflow.
 
 ### Document ingestion
 
-To broaden confidence beyond the current searchable-PDF fixtures, extend synthetic compatibility tests to cover Chromium-generated PDFs, common embedded fonts, multi-column documents, and tagged/untagged searchable PDFs. Continue to reject encrypted, image-only, malformed, oversized, or timed-out PDFs without OCR unless OCR receives separate authorization.
+The synthetic compatibility suite includes immutable Chromium 150/Skia fixtures for tagged and untagged searchable PDFs, a CSS multi-column document, and a reproducible ReportLab 4.4.10 two-page fixture. Searchable fixtures use an embedded OFL-licensed Lato subset. The suite pins reviewed fixture hashes, generator/tool-wheel coordinates, exact extracted text for the ReportLab document, and exercises the normal isolated scanner. Deterministic synthetic boundary cases verify that image-only, malformed, and oversized inputs fail closed without OCR.
+
+Further reviewed expansion may cover other common PDF generators and open-licensed embedded fonts. Continue to reject encrypted or timed-out PDFs and all text-unavailable documents without OCR unless OCR receives separate authorization.
 
 ### UX and context benchmarks
 
-The initial frozen synthetic benchmark covers the active/raw tool contracts, representative analyze and variant-review results, and the existing workbench prompt. Later benchmark expansion should cover:
+The versioned synthetic benchmark now covers Pi's stable always-visible `career-core` Skill name/description metadata, the complete on-demand `SKILL.md` for matching career tasks, the actual active/raw tool contracts, representative direct tool-call arguments, compact context/analyze/match/review/materialization results, evidence/change/document detail hydration, all six workbench prompts, the later reviewed-ID handoff, and independent end-to-end workflow rollups. Linked Skill references and machine-specific discovery location paths remain outside the measured context boundary. It records exact measured-surface SHA-256, tool calls, user model submissions, Skill-context occurrences, complete-source occurrences, repeated complete-source bytes, schema-discovery calls, and nested-JSON status alongside token totals; synthetic managed result/detail fixtures must match actual `career_run` serialization.
 
-- match, suggestion/replacement-review, materialization, and hydration result tokens
-- model turns and tool calls
-- mandatory warning/evidence/uncertainty retention
-- repeated private-source bytes
-- malformed-envelope prevention
-- TUI and RPC behavior
-- cold/warm runtime performance and memory
+The token-optimization study is intentionally split:
 
-Initial targets:
+1. `before_frozen` pins the post-save-workflow `c7d7634…` production `src/` and `skills/` Git trees, complete surface-digested benchmark snapshot, and snapshot SHA-256 before optimization;
+2. after the baseline merges, `optimizing` names that immutable baseline-history commit, verifies the frozen bytes from Git history, and lets the separately reviewed optimization merge only after all savings, no-regression, budget, shape, and invariant gates pass without requiring a self-referential after snapshot; and
+3. `after_frozen` adds a separately generated snapshot bound to the full merged optimization commit and its source/Skill tree IDs. The gate verifies that frozen snapshot and its exact deltas from immutable Git history; later current source may differ only when corpus/tokenizer/workflow shape, invariants, and budgets remain unchanged and no workflow regresses relative to the frozen after snapshot. The finalized snapshot is bound to `7ed36c4…` and records 25,652 → 21,552 aggregate workflow tokens (15.98% reduction), with every workflow reduced by 820 tokens.
 
+Predeclared after-phase targets:
+
+- at least 10% lower aggregate independent-workflow tokens with no workflow regression
 - primary active tool contract at or below 400 `o200k_base` tokens
 - no model-visible schema-export step in the managed flow
 - no nested `input_json`
-- original source included at most once per model workflow unless explicitly requested again
-- common result at or below roughly 1,500 tokens
-- complete authoritative detail recoverable on demand
+- original complete source included at most once per model workflow unless explicitly requested again
+- common result and detail at or below 1,500 tokens
+- required warning, uncertainty, authority, exact-selection, and detail-hydration semantics retained
 - review → explicit selection → materialization without rebuilding the Core envelope
 
+Provider wrappers, hidden prompts/reasoning, caching, and billing remain outside these tokenizer-proxy counts. Later benchmark expansion should add provider-specific tokenizer studies when reproducible local tokenizers are available, plus cold/warm runtime performance and memory without adding telemetry or private fixtures.
+
 ## Runtime boundaries retained after externalization
 
 Pi-career retains:
 
+- macOS/Linux-only package metadata and an adapter-level unsupported-platform failure before any route work or private stdin
 - no packaged native runtime artifacts or runtime dependencies
-- fixed resolution through explicit `CAREER_CLI_PATH`, PATH `career`, package-local exact `@revazi/career`, then acquisition of exact `@revazi/career@0.1.1`
+- fixed resolution through explicit `CAREER_CLI_PATH`, PATH `career`, package-local exact `@revazi/career`, then acquisition of exact `@revazi/career@0.2.0`
 - no Cargo, sibling checkout, source build, arbitrary executable download, unpinned package, or lifecycle fallback
 - `PI_OFFLINE=1` disables acquisition; the only implicit network-capable behavior is bounded exact-package acquisition after local routes fail and before private stdin opens
 - exact managed compatibility for caller-controlled routes and native integrity delegated to the reviewed package launcher

package/docs/design.md

@@ -12,41 +12,43 @@ The primary managed Pi surface is `career_run`. It uses ephemeral resume/result/
 
 `/career-tools managed|raw|status` controls whether the raw tools occupy active model context; it never changes the process, compatibility, privacy, or runtime-resolution boundary.
 
-The TypeScript source is authoritative. Checked-in deterministic `dist/index.js` and `dist/pdf-worker.js` bundles support clean local, pinned-Git, and npm Pi loading without packaged runtime dependencies. The isolated PDF worker bundles the reviewed text extractor; Pi-provided imports remain external peers. Package metadata permits only separately reviewed public publication of the unscoped `pi-career` package to the canonical npm registry.
+The TypeScript source is authoritative. Checked-in deterministic `dist/index.js` and `dist/pdf-worker.js` bundles support clean local, pinned-Git, and npm Pi loading without packaged runtime dependencies. The isolated PDF worker bundles the reviewed text extractor; Pi-provided imports remain external peers. Package metadata permits only separately reviewed public publication of the unscoped `pi-career` package to the canonical npm registry and declares only macOS/Linux installation through `os: ["darwin", "linux"]`.
 
-The workflow layer registers `/career-setup`, `/career-library`, `/career-application`, `/career-vacancy`, `/career-match`, `/career-analyze`, and `/career-workbench`. Setup/library scanning remains local. Core-backed commands use the same resolver and process helper as the tools. `/career-workbench` performs no provider/model call: it builds a bounded, visibly reviewable ordinary Pi editor prompt, and nothing leaves the package until the user separately submits that message through Pi. See [`product-flow.md`](product-flow.md) and [`application-workspaces.md`](application-workspaces.md).
+The workflow layer registers `/career-setup`, `/career-library`, `/career-application`, `/career-vacancy`, `/career-match`, `/career-analyze`, `/career-workbench`, the TUI-only `/career-review`, and the user-only TUI/RPC `/career-save`. Setup/library scanning remains local. Core-backed commands use the same resolver and process helper as the tools. `/career-workbench` performs no provider/model call: it builds a bounded, visibly reviewable ordinary Pi editor prompt, and nothing leaves the package until the user separately submits that message through Pi. `/career-review` also invokes neither Core nor a provider; it reads one current in-memory non-PDF variant review, collects explicit canonical IDs after warning/discard and exact-change inspection, and prepares a later editor message containing only the handle and IDs. See [`product-flow.md`](product-flow.md) and [`application-workspaces.md`](application-workspaces.md).
+
+The user-only `/career-save <variant-handle>` workflow is specified in [`variant-save-workflow.md`](variant-save-workflow.md). It accepts only a current successful non-PDF materialization, uses supported Pi TUI/RPC editor and confirmation dialogs, and writes nothing until the exact preview is returned unchanged and separately confirmed. Saving performs no Core/provider/network call, appends no session entry, and preserves all runtime-resolution, private-stdin, registry, and payload-free error boundaries in this document.
 
 ## Runtime resolution and compatibility
 
-Runtime routes are resolved in this fixed order:
+At extension initialization, pi-career requires macOS or Linux. Any other platform, including Windows, registers no command or tool and returns one stable payload-free `unsupported_platform` adapter error before reading or validating `CAREER_CLI_PATH`, traversing `PATH`, checking a package-local launcher, acquiring npm content, invoking a compatibility probe, or opening private stdin. Invocation and resolver entry points retain the same guard as defense in depth. On a supported platform, runtime routes are resolved in this fixed order:
 
 1. a bounded absolute `CAREER_CLI_PATH`, when explicitly set;
 2. the first executable `career` on the caller's `PATH`;
-3. a package-local exact `@revazi/career@0.1.1` launcher;
-4. bounded acquisition of exact `@revazi/career@0.1.1` from the canonical npm registry, followed by direct execution of the resolved launcher;
+3. a package-local exact `@revazi/career@0.2.0` launcher;
+4. bounded acquisition of exact `@revazi/career@0.2.0` from the canonical npm registry, followed by direct execution of the resolved launcher;
 5. otherwise a stable payload-free installation error.
 
 There is no sibling-checkout, Cargo, source-build, lifecycle-script, arbitrary URL/download, unpinned package, or PATH-selected npm/npx fallback. `PI_OFFLINE=1` disables route 4. The resolver caches only a successful route in process memory and invalidates it whenever the `CAREER_CLI_PATH` or `PATH` value changes.
 
-`CAREER_CLI_PATH`, PATH, and package-local installations are caller-controlled. Before any private operation opens stdin, the selected route must pass the exact managed compatibility surface: Core version `0.1.1`, all 15 `career.operation_catalog.v1` descriptors (capability mapping, CLI path, transport, schema IDs, input bounds, and 32-MiB output bound), and the required self-contained schema bundles with only valid local references. Explicit override failure never falls back. Automatically considered routes may be skipped during this payload-free compatibility phase. If a previously selected automatic executable later fails before its operation process emits `spawn`, the adapter may advance once to the next route; cancellation, timeout, or any already-started operation is never retried through another route.
+`CAREER_CLI_PATH`, PATH, and package-local installations are caller-controlled. Before any private operation opens stdin, the selected route must pass the exact managed compatibility surface: Core version `0.2.0`, all 15 `career.operation_catalog.v1` descriptors (capability mapping, CLI path, transport, schema IDs, input bounds, and 32-MiB output bound), and the required self-contained schema bundles with only valid local references. Explicit override failure never falls back. Automatically considered routes may be skipped during this payload-free compatibility phase. If a previously selected automatic executable later fails before its operation process emits `spawn`, the adapter may advance once to the next route; cancellation, timeout, or any already-started operation is never retried through another route.
 
-The package-local and acquired routes execute the reviewed `@revazi/career` launcher using the real Node executable. Pi-career validates the exact v2 launcher manifest, ordered eight-package catalog reference, lockstep optional-package map, and bounded launcher file before execution. The launcher remains responsible for native package selection, libc requirements, package/version/provenance mapping, regular-file type, Unix mode or Windows file invariant, size, format, architecture, and SHA-256 verification before it starts Career Core. Pi-career does not duplicate those native verification algorithms or package native files.
+The package-local and acquired routes execute the reviewed `@revazi/career` launcher using the real Node executable. Pi-career validates the exact v2 launcher manifest, ordered six-package catalog reference, lockstep optional-package map, declared file allowlist, `career` bin, and bounded launcher file before execution. The launcher remains responsible for native package selection, libc requirements, package/version/provenance mapping, regular-file type and Unix mode, size, format, architecture, and SHA-256 verification before it starts Career Core. Pi-career does not duplicate those native verification algorithms or package native files.
 
-Acquisition invokes the npm CLI derived from the real `process.execPath` installation using the reviewed Unix or Windows Node installation layout, rejects ambiguous or conflicting `npm_execpath`, pins the canonical registry/package/version, includes optional native packages, and disables lifecycle scripts. It never invokes an npm/npx executable selected from caller `PATH`. Unix acquisition pins `/bin/sh`; Windows acquisition validates `SystemRoot`, derives `System32/cmd.exe`, rejects conflicting `ComSpec`, sanitizes shell/PATH overrides, and uses that shell only inside npm's acquisition-only execution. npm's acquisition command prints only its controlled PATH through Node's `-p` option. From bounded stdout, pi-career requires exactly one absolute first PATH entry ending in `node_modules/.bin`, derives the fixed sibling `@revazi/career/bin/career.js`, and ignores platform-specific npm banner lines without exposing them. It then invokes the manifest-validated JavaScript launcher directly with real Node and `shell: false`; no npm command shim becomes the Career route.
+Acquisition invokes the npm CLI derived from the real Unix `process.execPath` installation, rejects ambiguous or conflicting `npm_execpath`, pins `/bin/sh` plus the canonical registry/package/version, includes optional native packages, and disables lifecycle scripts. It never invokes an npm/npx executable selected from caller `PATH`. npm's acquisition command prints only its controlled PATH through Node's `-p` option. From bounded stdout, pi-career requires exactly one absolute first PATH entry ending in `node_modules/.bin`, derives the fixed sibling `@revazi/career/bin/career.js`, and ignores npm banner lines without exposing them. It then invokes the manifest-validated JavaScript launcher directly with real Node and `shell: false`; no npm command shim becomes the Career route.
 
-Acquisition has fixed time/stdout/stderr bounds and sends no private stdin. The npm child starts in a detached process group: Unix cancellation signals the negative process-group ID, while Windows uses `CTRL_BREAK` for the detached npm group and a bounded forced pass for npm itself. Ordinary npm cache and `_npx` data may remain after acquisition; neither package removal nor `PI_OFFLINE=1` provides secure erasure.
+Acquisition has fixed time/stdout/stderr bounds and sends no private stdin. The npm child starts in a detached Unix process group; cancellation signals the negative process-group ID and makes a bounded forced pass after the grace period. Ordinary npm cache and `_npx` data may remain after acquisition; neither package removal nor `PI_OFFLINE=1` provides secure erasure.
 
-The reviewed `@revazi/career@0.1.1` launcher supplies `darwin-arm64`, `darwin-x64`, `linux-x64-gnu`, `linux-arm64-gnu`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64-msvc`, and `win32-arm64-msvc`. GNU Linux requires glibc 2.35 or newer. Unknown targets/libc, older glibc, and native integrity failures remain delegated to that launcher and surface only as bounded adapter failures. Windows PATH discovery remains direct-argv-only and considers native `career.exe`/`.com`/extensionless files, not caller-selected `.cmd` or `.bat` shells; package launchers use the validated package-local/acquired route instead.
+Pi-career's supported `@revazi/career@0.2.0` targets are `darwin-arm64`, `darwin-x64`, `linux-x64-gnu`, `linux-arm64-gnu`, `linux-x64-musl`, and `linux-arm64-musl`. GNU Linux requires glibc 2.35 or newer. Unknown supported-platform targets/libc, older glibc, and native integrity failures remain delegated to that launcher and surface only as bounded adapter failures.
 
 ## Process and privacy boundary
 
 The adapter calls `spawn(command, fixedArgv, { shell: false })`; operations and schema IDs are bounded before spawn. For package launcher routes, the fixed prefix is the validated launcher path invoked by the real Node executable. Document JSON is one bounded object string sent only through child stdin with `--input - --format json-compact`. Private stdin is not ended into the child until Node emits the successful `spawn` event.
 
-The process adapter creates no payload/result temporary files and adds no model, provider, telemetry, repair, URL-fetching, or command retry after launch. The sole network-capable runtime behavior is the bounded exact-package acquisition above, which finishes before private stdin opens. A successful Core child must emit exactly one UTF-8 JSON object with no stderr. Raw tools retain the 50,000-byte/2,000-line Pi-context ceiling and fail without partial output. Managed execution captures the complete Core result up to Core's declared 33,554,432-byte successful-machine-output ceiling. Complete managed results and exact review inputs live only in a 16-entry/64-MiB process-memory registry addressed by ephemeral handles; session/branch replacement and shutdown clear private entries. Model-visible projections/details remain capped at 50,000 bytes and never truncate the authoritative Core result.
+The process adapter creates no payload/result temporary files and adds no model, provider, telemetry, repair, URL-fetching, or command retry after launch. The sole network-capable runtime behavior is the bounded exact-package acquisition above, which finishes before private stdin opens. A successful Core child must emit exactly one UTF-8 JSON object with no stderr. Raw tools retain the 50,000-byte/2,000-line Pi-context ceiling and fail without partial output. Managed execution captures the complete Core result up to Core's declared 33,554,432-byte successful-machine-output ceiling. Complete managed results and exact review inputs live only in a 16-entry/64-MiB process-memory registry addressed by ephemeral handles; session/branch replacement and shutdown clear private entries. Model-visible projections/details remain capped at 50,000 bytes and never truncate the authoritative Core result. Variant review terminates its agent turn. For non-PDF originals, the TUI selector reads the exact retained changes from that registry, defaults all IDs to excluded, pages the selected exact records together with compact labels, permits direct read-only reopening of each selected record, and requires a separate final prepare choice before putting only an explicit selected-ID request in the editor; it appends no selection entry and performs no materialization or submission. PDF review entries are marked non-materializable in memory and fail closed in both selection and materialization.
 
-A direct Career Core operation timeout or abort sends `SIGTERM`, then `SIGKILL` after a bounded grace period, and settlement waits for close. npm acquisition uses detached process-group termination for descendants, including Windows `CTRL_BREAK` delivery rather than a PATH-selected tree-kill helper. stdout and stderr have independent byte ceilings. Fatal UTF-8, malformed/multiple success documents, successful stderr, signals, and stream failures map to stable errors. Only a strictly shaped, bounded, allowlisted `career.error.v1` may be nested in an adapter error. Source/result text, executable paths, hashes, platform/environment values, npm output, raw stderr, and filesystem/process errors are never logged or exposed.
+A direct Career Core operation timeout or abort sends `SIGTERM`, then `SIGKILL` after a bounded grace period, and settlement waits for close. npm acquisition uses detached Unix process-group termination for descendants rather than a PATH-selected tree-kill helper. stdout and stderr have independent byte ceilings. Fatal UTF-8, malformed/multiple success documents, successful stderr, signals, and stream failures map to stable errors. Only a strictly shaped, bounded, allowlisted `career.error.v1` may be nested in an adapter error. Source/result text, executable paths, hashes, platform/environment values, npm output, raw stderr, and filesystem/process errors are never logged or exposed.
 
-The workflow may read configured `.pdf`/`.md`/`.txt` roots, atomically persist non-content global config—including one bounded preferred variation-directory suggestion—and append consented custom session entries. Searchable PDF text is extracted from bounded in-memory bytes in a package-owned worker with fixed page, time, result, and memory ceilings; network fetch is disabled before the parser loads. No full Core result is appended to session state or written to a file, and pi-career has no full-result file export.
+The workflow may read configured `.pdf`/`.md`/`.txt` roots, atomically persist non-content global config—including one bounded preferred variation-directory suggestion—and append consented custom session entries. Searchable PDF text is extracted from bounded in-memory bytes in a package-owned worker with fixed page, time, result, and memory ceilings; network fetch is disabled before the parser loads. No full Core result is appended to session state or written to a file, and pi-career has no full-result file export. `/career-save` may persist only exact current assisted Markdown/text materialization bytes plus bounded package-owned marker/sidecar metadata after file-specific approval.
 
 ## Threat model
 
@@ -55,25 +57,28 @@ The workflow may read configured `.pdf`/`.md`/`.txt` roots, atomically persist n
 | Shell or argument injection | Fixed allowlisted operation mappings, bounded schema-ID syntax, direct argv-only spawn, `shell: false`, document bytes on stdin only. |
 | Executable substitution | Fixed route order; bounded absolute override; exact managed compatibility before private stdin; pinned canonical npm package; package launcher native verification. |
 | Malicious PATH/npm shadowing | PATH `career` remains caller-controlled and must pass compatibility. npm is derived from real Node, conflicting `npm_execpath` is rejected, and npm/npx is never selected from PATH. |
-| Unsupported or corrupted native package | The reviewed launcher validates target/libc, package lockstep, provenance, Unix mode or Windows file invariant, size, format, architecture, and SHA-256 and fails before native execution. |
+| Unsupported platform | Package metadata refuses installation outside macOS/Linux; direct Git/local extension initialization registers nothing and returns `unsupported_platform` before route work or private stdin. |
+| Unsupported or corrupted native package | The reviewed launcher validates target/libc, package lockstep, provenance, Unix mode, size, format, architecture, and SHA-256 and fails before native execution. |
 | Private input sent to multiple routes | Compatibility probes contain no private input. Only a failure before `spawn` may retry once; started, cancelled, and timed-out operations never retry. |
 | Acquisition sees private content | Acquisition completes before document stdin opens and receives no document bytes. `PI_OFFLINE=1` disables it. |
-| Hung acquisition descendants | Fixed acquisition timeout/output bounds, detached process groups, Unix group signals, and Windows `CTRL_BREAK` plus a bounded forced npm pass. |
+| Hung acquisition descendants | Fixed acquisition timeout/output bounds, detached Unix process groups, group signals, and a bounded forced pass. |
 | Oversized request, stream, diagnostic, memory, or context | Core-catalog input ceilings, independent stdout/stderr ceilings, fixed timeouts, raw context limits, 32-MiB managed capture, bounded registry, and 50,000-byte projections. |
 | Private payload disclosure in failures | Payload-free adapter errors; no source/result/path/environment/raw-error logging; only validated Core error envelopes may be nested. |
-| Persistence mistaken for erasure | Config contains no source/result content; managed results are process-memory-only; npm/Pi/session/cache data is explicitly not claimed to be securely erased. |
+| Automatic, ambiguous, or stale review selection | Variant review terminates the turn; exact warnings/discards and per-change evidence are paged locally; all IDs default excluded; selected exact records receive a compact labeled final cross-change review, direct read-only reopening, and a separate prepare-or-back choice; only confirmed canonical IDs in Core order enter a later editor message; stale/PDF handles fail closed. |
+| Unapproved or unsafe local variant persistence | Save is user-only, requires exact unchanged preview plus separate confirmation, forbids overwrite, publishes private sidecar-first pairs, and requires fail-closed rescanning before success. |
+| Persistence mistaken for erasure | Config contains no source/result content; managed results and live selector state are process-memory-only; a user-submitted prepared editor message may enter the Pi session; npm/Pi/session/cache data and any separately approved future artifacts are explicitly not claimed to be securely erased. |
 | Supply-chain or package drift | Exact external package coordinate, canonical registry, reviewed launcher delegation, four wildcard external Pi peers, no packaged runtime dependency/tree, deterministic dist, strict package allowlist, trusted npm/tar tooling, and clean low-threshold audits. |
 
 ## Build, package, CI, and installation boundary
 
 `npm run build` rebuilds only `dist/index.js` and `dist/pdf-worker.js`; it never builds, imports, or downloads native artifacts. The pi-career tarball contains no `runtime/`, native binary, `node_modules`, or Pi peer contents and declares no production/optional runtime dependency. Runtime acquisition is an invocation-time resolver route, not an npm lifecycle action.
 
-Package/audit orchestration invokes npm through `process.execPath` plus its derived absolute CLI and uses verified root-owned `/usr/bin/tar`, never PATH-selected npm/tar. Checks sanitize npm tree/severity overrides, reject duplicate decoded JSON keys, enforce exactly four wildcard external peers, verify extracted load/offline failure/install behavior, and require clean production/full audits at `--audit-level=low`. These Unix release gates remain separate from cross-platform runtime acceptance.
+Package/audit orchestration invokes npm through `process.execPath` plus its derived absolute CLI and uses verified root-owned `/usr/bin/tar`, never PATH-selected npm/tar. Checks sanitize npm tree/severity overrides, reject duplicate decoded JSON keys, enforce exactly four wildcard external peers and the macOS/Linux `os` allowlist, verify extracted load/offline failure/install behavior, and require clean production/full audits at `--audit-level=low`. The six-target external acceptance matrix covers every supported macOS/Linux runtime target.
 
-`test:career-package` separately exercises exact-package acquisition, managed Core 0.1.1 compatibility, and representative synthetic resume/job operations. The manually dispatched hosted External Career Compatibility workflow runs that acceptance natively for six release-gate targets: both macOS architectures plus GNU Linux x64/ARM64 and musl Linux x64/ARM64 in the exact pinned Alpine/Node container on native hosts. The macOS arm64 and Linux x64 GNU contexts run the complete release ladder; additional target jobs run build/type/runtime-boundary, exact-package, offline-load, and diff checks appropriate to their native environment. Ordinary pull requests run one required adapter job without external Career package acquisition; maintainers reserve the costly matrix for resolver/contract/platform changes and frozen releases.
+`test:career-package` separately exercises exact-package acquisition, managed Core 0.2.0 compatibility, and representative synthetic resume/job operations. The manually dispatched hosted External Career Compatibility workflow runs that acceptance natively for six release-gate targets: both macOS architectures plus GNU Linux x64/ARM64 and musl Linux x64/ARM64 in the exact pinned Alpine/Node container on native hosts. The macOS arm64 and Linux x64 GNU contexts run the complete release ladder; additional target jobs run build/type/runtime-boundary, exact-package, offline-load, and diff checks appropriate to their native environment. Ordinary pull requests run one required adapter job without external Career package acquisition; maintainers reserve the costly matrix for resolver/contract/platform changes and frozen releases.
 
 A user may register a reviewed clean absolute local path, public Git URL pinned to a full reviewed commit, or exact `npm:pi-career` version. Installing pi-career does not install Career Core through a lifecycle script. At first Core use, a compatible explicit/PATH/package-local route is preferred; otherwise the exact package may be acquired unless offline. Removal unregisters pi-career but does not erase Pi sessions, shell history, npm cache, Git clones, backups, or separately saved results.
 
 ## Provenance
 
-The initial process adapter, tool mappings, synthetic fake executable, process tests, and skill guidance were adapted from Career Core commit `100774ed8bb3b39c019d64ce105af1e3f209144f`. Managed-contract support was aligned with Career Core Phase 8 commit `f6d17835de4817e28ce84e8e5734ff592687dfcc`. The exact Core 0.1.1/eight-target launcher update was reviewed from Career Core commit `0318b3b0993ee23093c8f023757fa7e4d8b3b8e0` and protected publication run `31346152236`. Native distribution and integrity authority belong to exact `@revazi/career@0.1.1`, not pi-career.
+The initial process adapter, tool mappings, synthetic fake executable, process tests, and skill guidance were adapted from Career Core commit `100774ed8bb3b39c019d64ce105af1e3f209144f`. Managed-contract support was aligned with Career Core Phase 8 commit `f6d17835de4817e28ce84e8e5734ff592687dfcc`. The exact Core 0.2.0 six-target launcher contract was reviewed from Career Core commit `536690632884c17336cc3c108f1bba0f254b862b` and protected publication run `31761238274`; pi-career validates its exact ordered six-package v2 manifest while users address only the launcher package. Native distribution and integrity authority belong to exact `@revazi/career@0.2.0`, not pi-career.

package/docs/native-dependency-inventory.md

@@ -2,7 +2,7 @@
 
 ## Status and scope
 
-This is historical reproducible dependency evidence for the two native `career` binaries packaged by pi-career `v0.1.0` and its pre-external-resolver development candidate. Pi-career `v0.2.0` tracks and packages no native binary; native distribution evidence belongs to `@revazi/career`. This document is **not legal advice**, a legal-compliance conclusion, an SPDX/CycloneDX SBOM, or release approval.
+This is historical reproducible dependency evidence for the two native `career` binaries packaged by pi-career `v0.1.0` and its pre-external-resolver development candidate. Pi-career `v0.2.0` and later track and package no native binary; native distribution evidence belongs to `@revazi/career`. This document is **not legal advice**, a legal-compliance conclusion, an SPDX/CycloneDX SBOM, or release approval.
 
 The inventory is pinned to:
 

package/docs/product-flow.md

@@ -1,6 +1,6 @@
 # Product flow roadmap
 
-The cross-repository migration plan and measured findings are recorded in [`career-run-roadmap.md`](career-run-roadmap.md). Career Core Phase 8 and the first managed `career_run` implementation are complete; package-owned saving and PDF extraction expansion remain later phases.
+The cross-repository migration plan and measured findings are recorded in [`career-run-roadmap.md`](career-run-roadmap.md). Career Core Phase 8, the first managed `career_run` implementation, and the threat-reviewed package-owned Markdown/text save workflow in [`variant-save-workflow.md`](variant-save-workflow.md) are complete. Synthetic PDF compatibility covers reviewed Chromium-generated tagged/untagged and ReportLab-generated two-page documents, embedded-font and multi-column layouts, and fail-closed text-unavailable cases. The Git-history/tree/hash-bound token-optimization study is complete: its frozen before/after evidence includes Pi Skill discovery and matching-task full-Skill context and records a 15.98% aggregate workflow reduction with no workflow regression. Full application-workspace persistence and further PDF extraction expansion remain later phases.
 
 ## Current phase: managed agent tool and deterministic slash commands
 
@@ -19,9 +19,11 @@ It also registers:
 - `/career-match` for deterministic multi-resume matching and conservative ranking
 - `/career-analyze` for deterministic single-resume readiness detail
 - `/career-workbench` for a bounded, guided, visibly reviewable rebuild handoff to the user's normal Pi editor
+- `/career-review` for TUI-only, bounded inspection and explicit selection of current non-PDF retained variant changes
+- `/career-save` for user-only TUI/RPC exact preview, confirmation, and no-clobber local saving of one current Markdown/text materialization
 - `/career-tools` to switch between the managed-only and advanced raw model-tool surfaces
 
-`career_run`, the raw compatibility tools, `/career-vacancy`, `/career-match`, and `/career-analyze` invoke the compatible Career Core route selected by the external resolver. Managed compatibility is validated before private input, and the reviewed exact package may be acquired only after local routes fail unless `PI_OFFLINE=1`. `career_run` validates Phase 8 operation/schema contracts internally, resolves current originals/vacancy through ephemeral handles, keeps complete results in bounded process memory, and exposes compact detail hydration without nested `input_json`. Setup/library scanning remains local. `/career-application` manages consented session state only. `/career-workbench` does not invoke Core or a provider/model itself: it prepares an ordinary editor message containing one original resume and, only for tailoring, the current vacancy. Guided modes cover complete score explanation, reviewed improvement suggestions, a question-led factual interview before reviewed replacements, direct reviewed exact replacements, and vacancy-specific variant review. The user must review and submit that message separately through Pi.
+`career_run`, the raw compatibility tools, `/career-vacancy`, `/career-match`, and `/career-analyze` invoke the compatible Career Core route selected by the external resolver on supported macOS/Linux systems. Package metadata rejects other systems, and direct local/Git extension initialization registers no command/tool and fails with `unsupported_platform` before route work or private stdin. Managed compatibility is validated before private input, and the reviewed exact package may be acquired only after local routes fail unless `PI_OFFLINE=1`. `career_run` validates Phase 8 operation/schema contracts internally, resolves current originals/vacancy through ephemeral handles, keeps complete results in bounded process memory, and exposes compact detail hydration without nested `input_json`. Setup/library scanning remains local. `/career-application` manages consented session state only. `/career-workbench` does not invoke Core or a provider/model itself: it prepares an ordinary editor message containing one original resume and, only for tailoring, the current vacancy. Guided modes cover complete score explanation, reviewed improvement suggestions, a question-led factual interview before reviewed replacements, direct reviewed exact replacements, and vacancy-specific variant review. The user must review and submit that message separately through Pi. `/career-review` also invokes neither Core nor a provider: it reads one current in-memory non-PDF variant review, requires warnings/discards acknowledgment and exact per-change inspection before inclusion, then prepares a later editor message containing only the unchanged review handle and selected canonical IDs.
 
 Binding boundaries:
 
@@ -39,9 +41,12 @@ Binding boundaries:
 - workbench prompts keep originals immutable, omit absolute source paths, treat document text as untrusted data, rerun complete deterministic baselines after submission, and require Career Core review of external suggestions, replacements, and variant changes
 - workbench prompts may include a privacy-reduced preferred variation-directory display path from setup; the selected agent recommends it first only after a separate user request and receives no automatic write authority
 - review proposals use verbatim source targets and in-range evidence, prefer single-line targets, make one review attempt, and surface discard codes instead of model-led repair/retry loops
+- `career_run variant-review` terminates its turn; the TUI selector defaults every retained change to excluded, pages exact before/after/evidence locally, then pages selected changes together as compact labeled exact records, permits direct final-stage reopening of each record, and requires a separate prepare-or-back decision
+- review selection is process-memory-only: only the final prepare choice puts the ephemeral review handle and selected canonical IDs in the editor; pi-career appends no selection entry and performs no Core call
+- PDF review changes remain manual guidance; `/career-review` and `career_run materialize` reject PDF review handles because extracted text cannot preserve the styled document
 - raw tool JSON remains authoritative; managed projections refer to complete authoritative in-memory results by handle, while prose hydrates only requested evidence and retained items
 - PDF workbench output is suggestion-only because extracted text cannot expose or preserve visual layout; Markdown/text prompts require existing structure and unchanged wording to remain intact
-- no full-result file export unless a separate bounded local-file workflow is designed and tested
+- no full-result file export; `/career-save` persists only exact approved assisted document bytes and bounded marker/sidecar metadata
 
 The approved workflow specification fixes command behavior, persistence format, non-TUI behavior, bounded UI, and cancellation ownership. Print/JSON modes fail closed except for the pure `/career-vacancy clear` state action. Company/role isolation and future opt-in artifact persistence follow the separate [`application-workspaces.md`](application-workspaces.md) contract.
 
@@ -49,9 +54,9 @@ The approved workflow specification fixes command behavior, persistence format,
 
 The current workbench prepares private context in Pi's editor only. It does not call a model, hide the source payload, or write a document. Submitting is the user's separate provider action. The prompt directs the selected Pi agent to start with `career_run context`, use internal exact Phase 8 contract discovery, rerun and preserve complete deterministic baselines behind ephemeral handles, and pass external suggestions, replacements, or variant changes through the corresponding Career Core review before presenting them. The question-led rewrite mode reviews first, asks one bounded batch of user-verifiable factual questions, and waits for a later turn before drafting or reviewing exact replacements.
 
-For a non-PDF vacancy-specific variant, the first assisted turn must stop after review and ask the user to explicitly select Core-assigned canonical change IDs. Only a later turn may invoke deterministic materialization with exactly those selected IDs. The result remains assisted/non-authoritative and cannot enter authoritative analysis or matching. PDF workbenches stop after reviewed targeted changes for manual application and never materialize extracted text as a styled resume.
+For a non-PDF vacancy-specific variant, the first assisted turn stops mechanically after review. In TUI, the user can run `/career-review <review-handle>` to page all warnings/discards and exact retained changes. Every change starts excluded and can be included only from its exact detail view. Continuing pages all selected exact records together with compact labels and permits direct read-only reopening of each one; a separate final choice either returns to review or prepares—but never submits—the later user message with exactly the selected Core IDs and unchanged handle. Only after the user reviews and submits that message may deterministic materialization run. The result remains assisted/non-authoritative and cannot enter authoritative analysis or matching. PDF workbenches stop after reviewed targeted changes for manual application; PDF handles are rejected by selection and materialization and never turn extracted text into a styled resume.
 
-Automatic variant saving remains deferred. Setup now records or derives only a preferred destination suggestion: an explicit override wins, otherwise `variants/` under the selected original's configured root is recommended. It creates no directory or file. A future phase may save a newly materialized immutable assisted file only after separate local-file approval. It must not add provider fallback, automatic repair/retry, overwrite originals, auto-apply changes, or feed assisted output back into authoritative analysis/matching.
+Automatic variant saving remains prohibited. Setup records or derives only a preferred destination suggestion and creates no directory or file. After a successful non-PDF materialization, the user may separately run `/career-save <variant-handle>`: it derives an eligible direct-child managed destination, shows the complete exact plan, requires unchanged preview plus separate confirmation, performs no-clobber private writes, and succeeds only after fail-closed rescanning excludes the artifact from originals. It does not add provider fallback, automatic repair/retry, original overwrite, auto-application, or authoritative reranking.
 
 ## Non-goals in this phase
 
@@ -60,4 +65,4 @@ Automatic variant saving remains deferred. Setup now records or derives only a p
 - source-document or full-Core-result persistence outside the approved config/custom-entry workflow
 - source document mutation
 - career-document publication/export, release-asset downloads, signing, or notarization
-- package-owned native binaries or platform claims beyond the exact reviewed `@revazi/career@0.1.1` catalog
+- package-owned native binaries or platform claims beyond pi-career's six reviewed macOS/Linux targets; the launcher's additional upstream manifest entries are contract metadata, not support