Add Portable AI Kit CLI scaffold

[mdheller]

Summary

Adds the first SourceOS Portable AI Kit implementation slice.

This PR now includes:

• Portable AI Kit integration docs;
• portable-ai command routing through bin/sourceosctl;
• profiles, hardened preflight, prepare, inspect, and evidence helpers;
• BYOM local model file verification with SHA-256, size, license/provenance posture, optional copy into the portable root, and ModelCarryPack manifest output;
• runtime start/stop planning helpers that emit local endpoint, environment, command, surface handoff, and Agent Machine activation/teardown requirements without performing runtime side effects;
• standalone bin/sourceos-portable-ai compatibility entrypoint;
• unit tests for preflight, benchmark temp-file cleanup, dry-run and guarded materialization, BYOM verification, runtime planning, inspect, and evidence inspection;
• repo-local Homebrew formula under packaging/homebrew/Formula/sourceos-devtools.rb;
• docs/install.md install and smoke-test guide;
• scripts/validate_packaging.py and make validate wiring;
• README demo path, BYOM path, runtime planning path, and packaging posture.

Safety and governance posture

The slice keeps Portable AI Kit evidence-first and no-hidden-action by default:

• no implicit model downloads;
• no provider calls during BYOM verification;
• no implicit runtime start;
• no implicit process teardown;
• prompt egress denied by default;
• tool use denied by default;
• network access limited to local endpoint planning unless separately governed;
• local mutations require --execute --policy-ok where applicable.

Packaging path

Before tap promotion, the direct formula path is:

brew install --HEAD https://raw.githubusercontent.com/SourceOS-Linux/sourceos-devtools/main/packaging/homebrew/Formula/sourceos-devtools.rb

After tap promotion:

brew install SourceOS-Linux/tap/sourceos-devtools

Validation notes

Connector-visible workflow/status results for the current head SHA are empty, so CI is not confirmed through this path. Expected local validation:

python3 -m unittest discover -s tests -v
make validate
python3 scripts/validate_packaging.py
python3 bin/sourceosctl portable-ai profiles
python3 bin/sourceosctl portable-ai preflight /tmp/SOURCEOS_AI
python3 bin/sourceosctl portable-ai preflight /tmp/SOURCEOS_AI --benchmark
python3 bin/sourceosctl portable-ai prepare /tmp/SOURCEOS_AI --profile tiny-router --dry-run
python3 bin/sourceosctl portable-ai byom verify /tmp/SOURCEOS_AI ./models/example.gguf --name example
python3 bin/sourceosctl portable-ai start-plan /tmp/SOURCEOS_AI --provider ollama-compatible --surface turtleterm
python3 bin/sourceosctl portable-ai stop-plan /tmp/SOURCEOS_AI --provider ollama-compatible

Follow-up acceptance criteria

• Add Agent Machine activation/teardown receipt integration once runtime receipts land.
• Promote the formula into SourceOS-Linux/tap after merge and validation.
• Add signed model catalog entries after hash/license review.
• Add TurtleTerm consumer support for start-plan route descriptors.

[mdheller]

Capture update: superseded by #27.

#27 replayed the safe Portable AI Kit scaffold onto current main and merged as 32a6e98bf27ef2e2179d17ab12cba9510cdd1872.

Captured from this draft in reduced/current-main form:

• portable-ai route added to current bin/sourceosctl without overwriting newer command routers.
• Portable AI command parser and minimal helper modules.
• standalone bin/sourceos-portable-ai entrypoint.
• repo-local Homebrew formula scaffold.
• packaging validator and install/smoke guide.
• Makefile validation wiring while preserving current validation targets.

Validation observed on #27 head a7fd8d2d97bdbc992055e3db1d0ef1633d545acc:

• sourceos-devtools validate: success
• operation-conformance: success

Content status: core safe scaffold captured. This stale 58-behind draft should remain closed rather than merged directly.