Add Portable AI Kit CLI scaffold

Makefile

@@ -0,0 +1,13 @@
+.PHONY: validate test validate-packaging
+
+validate: test validate-packaging
+	@test -f README.md
+	@test -f docs/install.md
+	@test -f docs/integration/portable-ai-kit.md
+	@test -f packaging/homebrew/Formula/sourceos-devtools.rb
+
+test:
+	python3 -m unittest discover -s tests -v
+
+validate-packaging:
+	python3 scripts/validate_packaging.py

README.md

@@ -2,7 +2,7 @@
 
 `sourceos-devtools` is the installable SourceOS developer/operator toolkit surface.
 
-It is the home for Linux-native developer tooling, AI operator tooling, lab profile selection, Nix/devshell orchestration, NLBoot/operator helpers, release tooling, local AI governance utilities, and workstation bootstrap flows.
+It is the home for Linux-native developer tooling, AI operator tooling, lab profile selection, Nix/devshell orchestration, NLBoot/operator helpers, release tooling, local AI governance utilities, workstation bootstrap flows, and Portable AI Kit preparation flows.
 
 ## Scope
 
@@ -16,6 +16,7 @@ It should contain:
 - lab/profile selection utilities;
 - local model-service client helpers;
 - model-router client utilities;
+- Portable AI Kit preflight, prepare, BYOM verification, runtime start/stop plans, inspect, and evidence helpers;
 - guardrail/eval/evidence helpers;
 - agent sandbox/run helpers;
 - fingerprint and proof bundle tools;
@@ -34,6 +35,55 @@ It should not contain:
 - SourceOS image build state;
 - secrets, tokens, credentials, private keys, or device-specific enrollment secrets.
 
+## Portable AI Kit
+
+Portable AI Kit is the pocketable local-AI appliance mode for SourceOS: prepare a USB drive or portable SSD once, carry a governed local AI workstation, and run it on a supported host without sending prompts or chat state off-device by default.
+
+Quick demo path from a checkout:
+
+```bash
+python3 bin/sourceosctl portable-ai profiles
+python3 bin/sourceosctl portable-ai preflight /Volumes/SOURCEOS_AI
+python3 bin/sourceosctl portable-ai prepare /Volumes/SOURCEOS_AI --profile laptop-safe --dry-run
+python3 bin/sourceosctl portable-ai prepare /Volumes/SOURCEOS_AI --profile laptop-safe --execute --policy-ok --evidence-out ./portable-ai-evidence.json
+python3 bin/sourceosctl portable-ai start-plan /Volumes/SOURCEOS_AI --surface turtleterm
+python3 bin/sourceosctl portable-ai stop-plan /Volumes/SOURCEOS_AI
+python3 bin/sourceosctl portable-ai inspect /Volumes/SOURCEOS_AI
+```
+
+BYOM GGUF/local model verification path:
+
+```bash
+python3 bin/sourceosctl portable-ai prepare /Volumes/SOURCEOS_AI --profile byom-gguf --execute --policy-ok
+python3 bin/sourceosctl portable-ai byom verify /Volumes/SOURCEOS_AI ./models/example.gguf --name example --license-ref operator-attestation-required
+python3 bin/sourceosctl portable-ai byom verify /Volumes/SOURCEOS_AI ./models/example.gguf --name example --license-ref operator-attestation-required --execute --policy-ok --evidence-out ./byom-evidence.json
+python3 bin/sourceosctl portable-ai start-plan /Volumes/SOURCEOS_AI --provider ollama-compatible --surface turtleterm --model example
+```
+
+Runtime planning path:
+
+```bash
+python3 bin/sourceosctl portable-ai start-plan /Volumes/SOURCEOS_AI --provider ollama-compatible --host 127.0.0.1 --port 11434 --surface turtleterm
+python3 bin/sourceosctl portable-ai stop-plan /Volumes/SOURCEOS_AI --provider ollama-compatible --host 127.0.0.1 --port 11434
+```
+
+`start-plan` emits runtime environment variables, local endpoint refs, command hints such as `ollama serve`, surface handoff data, model-pack selection, and Agent Machine activation requirements. `stop-plan` emits teardown guidance and safe-eject prerequisites. Neither command starts daemons, kills processes, downloads models, grants network, grants tool use, or stores prompt bodies.
+
+BYOM verification hashes a local file, records size and SHA-256, and emits a `ModelCarryPack` manifest. It does **not** download a model, contact a provider, start a runtime, grant network, grant tool use, or store prompt bodies.
+
+Portable AI Kit does **not** download model weights implicitly, start local daemons implicitly, run inference during preflight, or authorize prompt egress by default. Runtime activation belongs to Agent Machine. Model pack definitions belong to `SourceOS-Linux/sourceos-model-carry`. Routing belongs to `SocioProphet/model-router` under Policy Fabric posture.
+
+Default profiles:
+
+| Profile key | Purpose | Minimum free space | Default posture |
+| --- | --- | --- | --- |
+| `tiny-router` | Routing, triage, rewrite, summarization | 8 GB | local-only, no tools |
+| `laptop-safe` | Offline fallback, Office assist, privacy-first chat | 16 GB | prompt egress denied |
+| `office-local` | Office Plane summarization and artifact drafting | 32 GB | workroom-scoped host writes |
+| `code-local` | Repo triage and local coding assistance | 32 GB | repo-scoped host writes |
+| `field-kit` | Field/operator portable SSD kit | 64 GB | evidence-first |
+| `byom-gguf` | Bring-your-own GGUF import profile | varies | hash required before eligibility |
+
 ## First milestone
 
 M1 is repo maturity and install surface definition:
@@ -50,6 +100,10 @@ M1 is repo maturity and install surface definition:
 - `SociOS-Linux/nlboot`: boot/recovery client and evidence records.
 - `SourceOS-Linux/sourceos-spec`: canonical SourceOS schemas and contracts.
 - `SourceOS-Linux/sourceos-boot`: SourceOS boot/recovery integration.
+- `SourceOS-Linux/sourceos-model-carry`: local model profiles and carry-layer service refs.
+- `SourceOS-Linux/agent-machine`: governed local runtime activation, teardown, and evidence receipts.
+- `SourceOS-Linux/TurtleTerm`: first-class terminal surface for Portable AI Kit.
+- `SourceOS-Linux/agent-term`: terminal-native SourceOS operator ChatOps console.
 - `SocioProphet/homebrew-prophet`: Homebrew install formulae.
 - `SocioProphet/model-router`: governed model/service routing.
 - `SocioProphet/guardrail-fabric`: guardrail policy client integration.
@@ -62,4 +116,4 @@ M1 is repo maturity and install surface definition:
 make validate
 ```
 
-The initial validation target checks repository metadata and JSON/YAML syntax where present. Implementation-specific validation should be added with each tool surface.
+The validation target checks repository metadata and runs the unit test suite. Implementation-specific validation should be added with each tool surface.

bin/sourceos-portable-ai

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Standalone SourceOS Portable AI Kit CLI."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# Allow running directly from the repo root without installing.
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from sourceosctl.commands.portable_ai_cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bin/sourceosctl

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""sourceosctl entry-point script."""
+import sys
+import os
+
+# Allow running directly from the repo root without installing.
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# Lightweight plugin routing for newer command groups while keeping the core
+# argparse surface stable. These command groups are non-mutating plan/probe
+# surfaces and own their own subparsers.
+if len(sys.argv) > 1 and sys.argv[1] == "network":
+    from sourceosctl.commands.network import network_main
+
+    sys.exit(network_main(sys.argv[2:]))
+
+if len(sys.argv) > 1 and sys.argv[1] == "native-assistant":
+    from sourceosctl.commands.network import native_assistant_main
+
+    sys.exit(native_assistant_main(sys.argv[2:]))
+
+if len(sys.argv) > 1 and sys.argv[1] == "portable-ai":
+    from sourceosctl.commands.portable_ai_cli import main as portable_ai_main
+
+    sys.exit(portable_ai_main(sys.argv[2:]))
+
+from sourceosctl.cli import main
+
+sys.exit(main())

docs/install.md

@@ -0,0 +1,82 @@
+# SourceOS Devtools Install Guide
+
+This guide documents the install surface for `sourceos-devtools`, including SourceOS Portable AI Kit commands.
+
+The install surface intentionally installs CLI/planning tools only. It does not install model weights, pull models, start local model runtimes, grant network access, or mutate a Portable AI Kit root by default.
+
+## Direct Homebrew install
+
+Before tap promotion, install from the repository formula:
+
+```bash
+brew install --HEAD https://raw.githubusercontent.com/SourceOS-Linux/sourceos-devtools/main/packaging/homebrew/Formula/sourceos-devtools.rb
+```
+
+After tap promotion:
+
+```bash
+brew install SourceOS-Linux/tap/sourceos-devtools
+```
+
+Validate:
+
+```bash
+sourceosctl portable-ai profiles
+sourceos-portable-ai profiles
+```
+
+## Checkout development flow
+
+```bash
+git clone https://github.com/SourceOS-Linux/sourceos-devtools.git
+cd sourceos-devtools
+python3 bin/sourceosctl portable-ai profiles
+python3 -m unittest discover -s tests -v
+```
+
+## Portable AI Kit smoke test
+
+Use a temporary or removable target root. The commands below do not download models or start daemons.
+
+```bash
+TARGET=/tmp/SOURCEOS_AI
+python3 bin/sourceosctl portable-ai preflight "$TARGET"
+python3 bin/sourceosctl portable-ai prepare "$TARGET" --profile laptop-safe --dry-run
+python3 bin/sourceosctl portable-ai prepare "$TARGET" --profile laptop-safe --execute --policy-ok --evidence-out ./portable-ai-evidence.json
+python3 bin/sourceosctl portable-ai start-plan "$TARGET" --provider ollama-compatible --surface turtleterm
+python3 bin/sourceosctl portable-ai stop-plan "$TARGET" --provider ollama-compatible
+python3 bin/sourceosctl portable-ai inspect "$TARGET"
+```
+
+## BYOM verification smoke test
+
+```bash
+TARGET=/tmp/SOURCEOS_AI
+mkdir -p ./tmp-models
+printf 'demo model bytes\n' > ./tmp-models/example.gguf
+python3 bin/sourceosctl portable-ai prepare "$TARGET" --profile byom-gguf --execute --policy-ok
+python3 bin/sourceosctl portable-ai byom verify "$TARGET" ./tmp-models/example.gguf --name example
+python3 bin/sourceosctl portable-ai byom verify "$TARGET" ./tmp-models/example.gguf --name example --execute --policy-ok --evidence-out ./byom-evidence.json
+```
+
+BYOM verification hashes a local file, records file size and SHA-256, writes a `ModelCarryPack` manifest only with `--execute --policy-ok`, and records that no download occurred.
+
+## Policy posture
+
+Default posture:
+
+- prompt egress is denied;
+- tool use is denied;
+- model downloads are explicit only;
+- runtime activation remains Agent Machine gated;
+- preflight is non-mutating unless `--benchmark` is requested;
+- `--benchmark` writes and removes a temporary local file and records cleanup in evidence;
+- runtime start/stop commands are plans only at this layer;
+- local model file materialization requires `--execute --policy-ok`.
+
+## Promotion path
+
+1. Land the repo-local formula.
+2. Validate direct formula install.
+3. Promote formula into `SourceOS-Linux/tap` after release checks.
+4. Add signed release artifacts and checksums once versioned packaging stabilizes.