Enhance CLI exit code handling and documentation updates

- Updated CLI commands to return non-zero exit codes for unavailable launch targets and command execution failures.
- Improved documentation in cli-reference.md to clarify exit codes and command behaviors.
- Revised cross-platform.md to reflect the current state of Linux and macOS enforcement capabilities.
- Enhanced final-report.md to provide a more accurate assessment of the repository's status and confidence levels.
- Added installation instructions for self-contained binaries in getting-started.md.
- Clarified the solution structure in solution-structure.md, emphasizing the current project roles and build capabilities.
- Implemented tests to verify daemon launch resolver behavior when no candidates are available.

Author: tmuskal

README.md

@@ -58,9 +58,10 @@ dotnet run --project src/AgentPowerShell.Cli -- policy validate default-policy.y
 ## Release And CI
 
 - Pull requests and pushes to `main` and `master` run .NET build/test jobs on Windows, Linux, and macOS.
+- The CI matrix now also smoke-tests published install outputs, not just repo-local `dotnet` execution paths.
 - Docker smoke coverage runs on Linux and Windows GitHub-hosted runners. macOS runners only execute the direct .NET test matrix because hosted macOS runners do not expose a Docker daemon.
 - Release tags use semantic versioning in the form `vMAJOR.MINOR.PATCH`.
-- Tagged releases publish CLI artifacts and Linux multi-arch Docker images under the `a5c-ai` GitHub organization.
+- Tagged releases publish packaged CLI + daemon artifacts and Linux multi-arch Docker images under the `a5c-ai` GitHub organization.
 - The nightly workflow publishes `edge` container images to `ghcr.io/a5c-ai/agentpowershell`.
 
 ## Status

docs/architecture.md

@@ -22,15 +22,15 @@ Resolution order:
 - sibling `AgentPowerShell.Daemon(.exe|.dll)` next to the current binaries
 - `src/AgentPowerShell.Daemon/AgentPowerShell.Daemon.csproj` from the repo root
 
-If no launch target is discoverable, the command returns `status: unavailable` with guidance.
+If no launch target is discoverable, the command returns `status: unavailable` with guidance and exits non-zero.
 
 ### `stop`
 
 Stop the tracked daemon PID from `.agentpowershell/daemon.json` and remove that state file. If the process is already gone, the command still cleans up the stale state.
 
 ### `exec <session-id> <command...>`
 
-Execute an explicit command in a session through the current daemon processor path. Inline PowerShell commands route through the hosted constrained runspace when supported. Interactive shell launches such as bare `powershell` or `pwsh` are rejected by design.
+Execute an explicit command in a session through the current daemon processor path. Inline PowerShell commands route through the hosted constrained runspace when supported. Interactive shell launches such as bare `powershell` or `pwsh` are rejected by design. The CLI process exits with the underlying command or policy result code.
 
 ### `session create`
 

docs/cli-reference.md

@@ -8,17 +8,18 @@ The repository currently has the first real Windows-specific enforcement slice i
 
 ## Linux
 
-The Linux project captures the intended abstraction boundaries, but the repository does not yet provide runtime-complete cgroups, Landlock, seccomp-bpf, ptrace, eBPF, or namespace enforcement. Current Linux support should be treated as buildable structure plus shared policy behavior, not production-grade sandboxing.
+The Linux project captures the intended abstraction boundaries, but the repository does not yet provide runtime-complete cgroups, Landlock, seccomp-bpf, ptrace, eBPF, or namespace enforcement. Today the Linux platform code primarily turns policy into enforcement plans plus shared behavior; it should not be treated as production-grade sandboxing.
 
 ## macOS
 
-The macOS project likewise reflects the planned abstraction surface for Endpoint Security, sandbox-exec, Network Extension, FSEvents, RLIMIT, and XPC, but those integrations are not yet wired into a verified runtime enforcement path.
+The macOS project likewise reflects the planned abstraction surface for Endpoint Security, sandbox-exec, Network Extension, FSEvents, RLIMIT, and XPC, but those integrations are not yet wired into a verified runtime enforcement path. As with Linux, the current macOS code is closer to planning/scaffolding than finished native enforcement.
 
 ## Practical Guidance
 
 - Keep shared models and policy logic in `AgentPowerShell.Core`.
 - Put platform-native behavior behind explicit abstractions.
 - Validate cross-platform projects in CI for every change.
 - Treat Docker support as Linux-container packaging that is smoke-tested on Linux and Windows runners; GitHub-hosted macOS runners do not provide Docker.
+- Treat native Linux/macOS install validation as a separate verification step from Windows install coverage.
 - Prefer runtime-specific integration tests before claiming full feature parity on a platform.
 - Phrase current support in terms of verified behavior, not architectural intent.

docs/cross-platform.md

@@ -2,29 +2,31 @@
 
 ## Verdict
 
-AgentPowerShell is a strong repository-level baseline, not yet a finished fulfillment of the broader `agentsh`-style specification. It has a passing build, passing automated tests, a defined CLI surface, and concrete implementations for sessions, events, approvals, authentication, LLM proxying, MCP inspection, reporting, checkpoints, and the current command-execution path.
+AgentPowerShell is a usable repository-level baseline, not a finished fulfillment of the broader `agentsh`-style specification. It now has a passing build, passing automated tests, a verified install-publish path on Windows, a passing Docker smoke path, a defined CLI surface, and concrete implementations for sessions, events, approvals, authentication helpers, MCP/LLM support, reports, checkpoints, and the current command-execution path.
 
 ## Strengths
 
 - Clear multi-project separation between shared models, daemon services, CLI, events, proxying, MCP, and platform-specific code
 - Policy and config primitives are simple, testable, and easy to extend
 - End-to-end build and test verification is green across unit, integration, and platform test projects
+- Install and Docker publish flows are now exercised through real smoke coverage rather than only by static configuration
 - The CLI now executes real checkpoint operations instead of placeholder output
 - Hosted PowerShell execution and explicit policy-backed command blocking are now exercised through the tested runtime surface
 
 ## Concerns
 
 - Some cross-platform enforcement capabilities remain scaffolding rather than runtime-complete implementations
-- Packaging assets are ready for CI and publish flows, but signing and installer distribution still need production secrets and release hardening
+- Native Linux/macOS install execution and real tagged-release execution still need runner-backed confirmation beyond this local Windows session
+- Signing and installer distribution still need production secrets and release hardening
 - Feature parity claims against `agentsh` should continue to be framed carefully until deeper platform-native enforcement paths are completed
 
 ## Follow-Up Tasks
 
-1. Add runtime integration coverage for checkpoint restore interactions during active daemon/session workflows.
+1. Correct remaining architecture-oriented docs so they describe verified runtime behavior instead of target-state intent.
 2. Expand platform-specific tests from build validation into behavior validation on Windows, Linux, and macOS runners.
 3. Turn the code-signing placeholder into an operational signing pipeline with secret-backed configuration.
 4. Add lifecycle management for checkpoint retention and deletion.
 
 ## Confidence
 
-Confidence is high for repository health and implementation quality, and moderate for production-readiness of the platform-native enforcement story.
+Confidence is high for repository health and current packaging/runtime verification, and moderate for production-readiness of the platform-native enforcement story.

docs/final-report.md

@@ -15,6 +15,18 @@ dotnet test agentpowershell.sln --verbosity minimal --no-build
 
 ## First Commands
 
+If you want self-contained binaries instead of `dotnet run`, use:
+
+```powershell
+./install.ps1
+```
+
+or on native Unix shells:
+
+```bash
+./install.sh
+```
+
 Print the CLI version:
 
 ```powershell
@@ -73,7 +85,9 @@ dotnet run --project src/AgentPowerShell.Cli -- checkpoint restore latest --dry-
 ## Current Boundaries
 
 - `exec` supports explicit commands; it does not yet provide an interactive shell session.
-- Inline PowerShell commands route through a hosted constrained runspace.
+- Inline PowerShell commands route through the hosted execution path that exists today; the broader PSHost/ConstrainedLanguage architecture remains target direction, not a fully verified parity story.
 - Native commands use the daemon processor path and current policy prechecks.
+- `exec` now returns the underlying command or policy exit code to the calling shell, so denials and runtime failures are observable to automation.
 - The shim will attempt to connect to the daemon first and will auto-start it only when a daemon command, binary, or source project can be discovered.
 - Cross-platform sandboxing is still uneven; Windows has the most concrete runtime enforcement today.
+- Network blocking currently means explicit-target policy filtering, not full OS-level egress interception.