docs: architecture v2, internal maintainer docs, and error-handling guide - #858

docs/ci-strategy.md (1)

32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Prefer a repository-relative link for CONTRIBUTING.md.

Linking directly to main makes this document resolve against potentially different guidance than the version being reviewed, especially for release branches or forks. Use a relative link such as [CONTRIBUTING.md](../CONTRIBUTING.md) if the documentation site supports it.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/ci-strategy.md` at line 32, Update the CONTRIBUTING.md link in the CI
strategy documentation to use a repository-relative path such as
../CONTRIBUTING.md instead of the main-branch GitHub URL, preserving the
existing link text.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

docs/ci-strategy.md (1)

32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Prefer a repository-relative link for CONTRIBUTING.md.

Linking directly to main makes this document resolve against potentially different guidance than the version being reviewed, especially for release branches or forks. Use a relative link such as [CONTRIBUTING.md](../CONTRIBUTING.md) if the documentation site supports it.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/ci-strategy.md` at line 32, Update the CONTRIBUTING.md link in the CI
strategy documentation to use a repository-relative path such as
../CONTRIBUTING.md instead of the main-branch GitHub URL, preserving the
existing link text.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

docs/internal/session-domain-diag.md (1)

121-130: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Reconcile the VM socket transport contract.

This section says guest minimald creates a Unix socket that minvmd proxies, but docs/architecture.md says minimald serves SSH directly on a vsock port and minvmd bridges host UDS to that vsock port. These are different topologies; update one document so the provider contract is unambiguous.

Proposed wording if the architecture page is authoritative

-- The in-VM `minimald` creates its own socket inside the guest.
-- `minvmd` **proxies/forwards** that guest socket back to the host, so host `Minimal` talks to the in-VM `minimald` through `minvmd`.
-- `Minimal` connects to `minvmd`'s host socket; `minvmd` relays traffic across the VM boundary to each VM's `minimald`.
+- The in-VM `minimald` serves SSH directly on its vsock port.
+- `minvmd` bridges its host-facing Unix socket to that guest vsock port.
+- `Minimal` connects to `minvmd`'s host socket; `minvmd` relays traffic across the VM boundary to the in-VM `minimald`.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

- The in-VM `minimald` serves SSH directly on its vsock port.
- `minvmd` bridges its host-facing Unix socket to that guest vsock port.
- `Minimal` connects to `minvmd`'s host socket; `minvmd` relays traffic across the VM boundary to the in-VM `minimald`.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/internal/session-domain-diag.md` around lines 121 - 130, Reconcile the
VM transport description in the Mermaid flow and surrounding bullets with the
authoritative contract in docs/architecture.md: describe guest minimald as
serving SSH on a vsock port, and minvmd as bridging the host Unix socket to that
vsock endpoint rather than proxying a guest Unix socket. Keep the Minimal →
minvmd → minimald → Session flow while making the socket types and bridge
responsibility explicit.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

docs/error-handling.md (1)

79-89: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect the relevant section and search for related conventions
sed -n '60,110p' docs/error-handling.md

printf '\n--- search for color_eyre / install / eyre ---\n'
rg -n "color_eyre|color-eyre|color-eyre::install|color_eyre::install|anyhow|eyre" -S .

printf '\n--- list docs files maybe relevant ---\n'
git ls-files 'docs/*' 'README*'

Repository: gominimal/minimal

Length of output: 35111

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '1,80p' docs/rust-coding-standards.md
printf '\n--- color_eyre in manifest/docs ---\n'
rg -n "color_eyre|color-eyre|install\\(" Cargo.toml crates docs -S

Repository: gominimal/minimal

Length of output: 6478

---

🌐 Web query:

color-eyre install report handler CLI entrypoint documentation color_eyre::install()

💡 Result:

The color-eyre::install function is used to initialize the panic and error report handlers for the color-eyre crate, which provides colorful, well-formatted error reporting in Rust applications [1][2]. To use it in a CLI entrypoint, you should call it as one of the very first actions within your main function, before any errors are constructed or other report handlers are installed [1]. Usage pattern: 1. Add color-eyre to your Cargo.toml dependencies [3][4]. 2. Call color_eyre::install at the start of your main function [1][3]. Example implementation: use color_eyre::eyre::Result; fn main -> Result<> { // Install the default panic and error report hooks color_eyre::install?; // Proceed with your application logic Ok() } Key considerations: - The function returns a Result<, Report> [1]. - It can only be installed once; calling it again after another handler has been set will return an error [1]. - It must be called before any eyre::Report is constructed to ensure the default handler is properly configured [1]. - If you are also using tracing for diagnostics, ensure that color_eyre::install is integrated correctly with your tracing subscriber, typically after setting up your error layer [5].

Citations:

• 1: https://docs.rs/color-eyre/latest/color_eyre/fn.install.html
• 2: https://crates.io/crates/color-eyre
• 3: https://docs.rs/color-eyre/latest/color_eyre/
• 4: https://github.com/eyre-rs/color-eyre
• 5: https://github.com/yaahc/color-eyre/blob/master/examples/usage.rs

---

Clarify the color_eyre boundary. color_eyre still needs color_eyre::install() at CLI startup to provide the formatted reports, so “drop-in substitute” is too strong. Soften this to describe it as an application-boundary replacement and mention the startup hook for CLI entrypoints.

🧰 Tools

🪛 LanguageTool

[style] ~81-~81: To elevate your writing, try using an alternative expression here.
Context: ... anyhow where the specific error type does not matter and errors are only propagated upward. ...

(MATTERS_RELEVANT)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/error-handling.md` around lines 79 - 89, Clarify the “User-facing CLIs —
color_eyre instead of anyhow” section to describe color_eyre as an
application-boundary replacement rather than a drop-in substitute, and
explicitly state that CLI entrypoints must call color_eyre::install() during
startup to enable formatted reports.

Source: MCP tools

docs/internal/licensing.md (1)

29-34: 🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

Separate Cargo.lock pinning from LGPL source-delivery compliance.

Cargo.lock pins the selected git revision; it does not contain the crate sources or demonstrate that distributed binaries include the materials needed for relinking. For statically linked LGPL components, document the actual source/object-file distribution mechanism rather than claiming that the lockfile and repository alone satisfy the requirement. (gnu.org)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/internal/licensing.md` around lines 29 - 34, Update the licensing
discussion around “Stance: document and accept” to separate Cargo.lock’s
dependency-revision pinning from LGPL source-delivery compliance. Replace the
claim that the repository and lockfile alone satisfy relinking requirements with
the actual mechanism used to distribute the complete corresponding source and,
for static linking, required object files or equivalent relinking materials;
retain the existing distribution-model context only if it accurately describes
that mechanism.

Source: MCP tools

docs/internal/session-domain-diag.md (2)

83-87: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Align the VM transport description with docs/architecture.md.

These sections describe proxying a guest socket, while docs/architecture.md states that minimald serves SSH directly on a guest vsock port and minvmd bridges host UDS → guest vsock. Use one consistent topology and diagram to avoid implementing the wrong socket path.

Also applies to: 103-111, 119-130

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/internal/session-domain-diag.md` around lines 83 - 87, Update the VM
transport topology in the diagrams around the guest subgraph and the additional
referenced sections to match docs/architecture.md: show minimald serving SSH
directly on the guest vsock port, with minvmd bridging the host Unix domain
socket to that guest vsock. Remove the guest-socket proxying path and ensure all
related labels and arrows consistently represent this transport.

---

142-157: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Start missing configured providers when discovery is partial.

The live sockets found? yes-branch connects to discovered sockets and skips configuration processing, but the stated rule says configuration starts all listed providers. Change the flow to reconcile configured providers after discovery, or narrow the rule so this behavior is unambiguous.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/internal/session-domain-diag.md` around lines 142 - 157, The documented
bootstrap flow must start every configured provider even when discovery finds
some live sockets. Update the “live sockets found?” branch and configuration
flow so discovered sockets are connected while any configured providers not
already live are also started; preserve the no-config system-default behavior
and clarify the bootstrap rules if needed.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes