Preview managed local AI and OCR setup

These workflows are previews: each section states whether it is available on SHAFT_ENGINE main or in a published release. Every install follows the shared review and approve flow; policy options and exit codes are in the infrastructure reference.

Preview managed local AI

Not in a published release yet

The LOCAL_AI managed provider is available on SHAFT_ENGINE main after engine PR #4921. The delivered merge commit is a585b41980f78315aa353003ce5b5891f350a6a1. Use this workflow with a source build until a containing SHAFT release is published.

Use this profile when you want SHAFT to own a pinned llama.cpp runtime and a reviewed GGUF model. You do not need a model manager, container, service, endpoint, credential, administrator install, or machine-wide daemon. SHAFT starts an authenticated loopback child process only when an approved AI request needs it.

SHAFT continuously measures aggregate resident memory for the managed process tree. If the tree exceeds 4 GiB, or its live memory inventory cannot be read safely, SHAFT retires the session and returns the request's deterministic fallback.

Start with explicit provisioning. Enable managed local processing, select the manual compact candidate, and prevent an inference request from downloading missing artifacts before you review the setup plan:

src/main/resources/properties/custom.properties
managedLocalAi.enabled=true
managedLocalAi.transparentProvisioning=false
managedLocalAi.model=qwen3-0.6b-q8_0

Run the shared review flow. Stop after plan, inspect both actions and the printed digest, then install that exact plan:

Review and install managed local AI
shaft-cli setup status --profile LOCAL_AI --mode MANAGED
shaft-cli setup plan \
  --profile LOCAL_AI \
  --mode MANAGED \
  --operation INSTALL \
  --output /absolute/path/local-ai-plan.json
shaft-cli setup install \
  --plan /absolute/path/local-ai-plan.json \
  --approve sha256:<reviewed-digest> \
  --accept-license MIT \
  --accept-license Apache-2.0
shaft-cli setup verify --profile LOCAL_AI --mode MANAGED
shaft-cli doctor local-ai-status

The plan binds the exact runtime and model URL, version or revision, SHA-256, license, and artifact size. Installation reports phase, completed bytes, total bytes, and integer percentage on stderr, so --json output on stdout stays machine-readable. An interrupted, failed, or cancelled operation returns no receipt; fix the reported condition and retry the same still-current approved plan.

Leave --cache-root and --data-root unset to use the effective managed-local cache and the normal SHAFT data root. If you supply roots, pass both as absolute paths on plan and install, and make --cache-root exactly equal to managedLocalAi.cacheDirectory. SHAFT rejects a different cache instead of provisioning files that inference will not use.

Inspect readiness and privacy-safe diagnostics

Use setup status or setup verify for the two managed targets. Those commands print target readiness version detail. Version is empty unless READY. They report readiness/version/action, not the reviewed pin table.

Use doctor local-ai-status or MCP doctor_managed_local_ai_status for enablement, eligibility, and the DISABLED snapshot. They do not list the reviewed pin table.

The MCP setup equivalents are setup_status, setup_verify, setup_plan, and setup_install. IntelliJ uses those generic MCP setup tools instead of a second lifecycle implementation.

The pin table on this page is the documented inventory. Setup commands do not print revision, license, provenance, size, floors, update, cleanup, or fallback. Diagnostics exclude absolute cache paths, filenames, checksums, executable names, and exact host RAM, CPU, and free-disk values.

warning

Managed-local enablement grants local-processing consent only. It does not grant remote or on-premises processing consent. The compact candidate failed the current recommendation-quality gates, so use it only for manual evaluation and keep deterministic SHAFT results authoritative. managedLocalAi.enabled defaults to false. Do not flip that default to enable managed-local automatically.

Inventory, defaults, and troubleshooting

The pin table on this page is the documented inventory. setup status and setup verify print target readiness version detail even when the cache is missing or the feature is still disabled. Version is empty unless READY. Commands report readiness/version/action, not those pin-table fields:

Field	Compact preview pin
Revision	runtime `b10400` / model `23749fefcc72300e3a2ad315e1317431b06b590a`
License	`MIT` / `Apache-2.0`
Provenance	`github.com/ggml-org/llama.cpp` and `huggingface.co/Qwen/Qwen3-0.6B-GGUF`
Size	platform runtime archive plus `639446688` model bytes
Storage	`SHAFT_USER_CACHE` — never an absolute cache path
Resources	compact floor `2` GB RAM, `2` CPUs, `3` GB free disk
Update	explicit reviewed plan; pin-bound; no silent float
Cleanup	owner-manifest only; unknown siblings preserved
Fallback	deterministic SHAFT result remains authoritative

Release automation cannot float or silently replace model or runtime bytes. A revoked or hash-mismatched artifact stays unpublished; the last good activation remains active. An interrupted upgrade returns no receipt and does not activate the new pair. Offline setup reuses a ready cache and never downloads or substitutes a fallback URL.

Inspect readiness from each setup surface:

Surface	Command
CLI	`shaft-cli setup status --profile LOCAL_AI --mode MANAGED` and `shaft-cli setup verify --profile LOCAL_AI --mode MANAGED`
MCP	`setup_status` and `setup_verify`
IntelliJ	the generic MCP setup tools; there is no second lifecycle
CI / headless	keep `managedLocalAi.enabled=false`; normal Maven never provisions or downloads; always pass `-Dallure.automaticallyOpen=false`

shaft-cli doctor local-ai-status and doctor_managed_local_ai_status report enablement, eligibility, and the DISABLED snapshot. They do not list the reviewed pin table.

If Maven or CI needs a local-AI assertion, run the unit tests that inspect status, setup, cache, and properties. Do not add a provision or benchmark step to a default pipeline. If a job must stay offline, pass --offline on both plan and install; a missing or revoked pin fails closed.

Clean, update, and roll back

Create and approve a separate plan for every maintenance operation. Clean removes only unchanged installations owned by the current reviewed manifest; changed, unknown, and other-version content is preserved. If changed or unknown owned content blocks cleanup, the command returns a generic failure without a receipt rather than listing each preserved installation:

shaft-cli setup plan \
  --profile LOCAL_AI \
  --mode MANAGED \
  --operation CLEAN \
  --output /absolute/path/local-ai-clean.json
shaft-cli setup install \
  --plan /absolute/path/local-ai-clean.json \
  --approve sha256:<reviewed-digest> \
  --accept-license MIT \
  --accept-license Apache-2.0

Clean verifies the activation record and every selected installation before it removes anything. If changed or unknown content blocks cleanup, SHAFT preserves the verified active/previous record and its rollback candidate. After the reviewed artifacts clean successfully, SHAFT clears the activation record, so provision and activate two different reviewed pairs again before expecting ROLLBACK planning to succeed.

For an update, create a new INSTALL plan from the current release and apply it with setup install or its setup update alias. SHAFT provisions the new content-addressed pair before activation and retains one exact prior reviewed pair.

Rollback is available only after two different reviewed pairs have activated successfully and the prior pair still verifies exactly. It swaps the cached active and previous pairs without downloading or deleting artifacts:

shaft-cli setup plan \
  --profile LOCAL_AI \
  --mode MANAGED \
  --operation ROLLBACK \
  --output /absolute/path/local-ai-rollback.json
shaft-cli setup install \
  --plan /absolute/path/local-ai-rollback.json \
  --approve sha256:<reviewed-digest> \
  --accept-license MIT \
  --accept-license Apache-2.0

SHAFT rechecks the approved candidate, complete owned file inventories, and current host eligibility under the cache lock before changing activation. A missing, changed, corrupt, or newly ineligible prior pair fails without a rollback receipt.

Preview: managed OCR setup

Not released

This workflow is not yet available on SHAFT_ENGINE main or in a published SHAFT release. Keep using the current OCR first-use model flow until a release that contains the complete setup stack is available.

The preview defaults to the eng and ara model bundle. Omit --language to use that bundle, or repeat exact Tesseract codes on plan and selected status/verify commands. Install recovers the selected languages from the reviewed plan:

shaft-cli setup plan --profile OCR --mode MANAGED \
  --language fra --language deu \
  --output /absolute/path/ocr-plan.json
shaft-cli setup install --plan /absolute/path/ocr-plan.json \
  --approve sha256:<reviewed-digest>
shaft-cli setup verify --profile OCR --language fra --language deu

The reviewed actions bind the normalized component set. Repeating --language during install is optional and must match when supplied. The planned OCR provider enforces --offline: it can accept a verified installed model, legacy model, or artifact-cache entry without network access. It has no start, stop, or logs lifecycle.