oss/integration repo hygiene - #840

Add package.license to the [workspace] block and switch every crate to
license.workspace = true: 17 crates previously hardcoded the SPDX
expression and 11 carried no license key at all. All 28 workspace
crates now inherit the single declaration.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Add LICENSE-APACHE (canonical Apache-2.0 text, appendix fields left as
boilerplate) and LICENSE-MIT (The Minimal Authors), a NOTICE file with
the dual-license statement and attribution for the two Apache-2.0
binaries redistributed in darwin/arm64 release artifacts (libkrun
v1.19.4, gvproxy v0.8.9, versions per the vendor lock files), an
internal docs/internal/licensing.md recording the LGPL stance for the
malachite crates and hakoniwa plus the crates.io publishing blocker,
and a README License section with the standard contribution-licensing
sentence.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…allowance

Replace the placeholder comment above the license exceptions with a
block explaining the hakoniwa and malachite LGPL entries and pointing
at docs/internal/licensing.md. Remove [sources.allow-org] github =
["souk4711"]: hakoniwa 1.7.2 now comes from crates.io and Cargo.lock
has zero souk4711 hits, so the allowance is dead. cargo deny check
licenses sources passes ('licenses ok, sources ok'); the pre-existing
warn-level source-not-allowed for the nickel-lang git dependency is
unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

SECURITY.md routes vulnerability reports through GitHub private
vulnerability reporting (never public issues), maps supported
versions to the installer's release channels (stable supported;
unstable/nightly latest-only, no backports), and scopes the policy
to the shipped binaries, the installer, and the sandbox/microVM
isolation boundaries.

CODE_OF_CONDUCT.md is the Contributor Covenant v2.1, with the
enforcement contact left as the covenant's placeholder pending a
launch decision.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…late

The ISSUE_TEMPLATE markdown files were untouched GitHub boilerplate
(browser/smartphone fields on a CLI tool). Replace them with issue
forms tuned to minimal: the bug form captures version output, OS/arch,
install channel, and logs; the feature form asks for problem,
proposal, and alternatives. config.yml disables blank issues, with
contact links left commented out pending the Discussions decision.

The PR template reminds that the title becomes the squash commit
subject (Conventional Commits), asks for testing evidence, and
carries docs/breaking-change checkboxes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The clap command was still named "minimal" (its pre-rename identity),
but the binary ships as bin/mip. As a result, generated shell
completions registered under the wrong command name, so
`mip completions` produced a script that completed a nonexistent
`minimal` command. Rename the clap command to "mip", update the about
string, and fix all help/usage text and `mip init` next-step hints
that still told users to run `minimal <subcommand>`.

Strings that legitimately refer to minimal.toml, the minimal project,
paths, or environment variables are unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The completions long_about example said `minimal completions bash`,
which is the wrong binary; the daemon's own completions are generated
with `minimald completions bash`.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Replace the single cli.md (which documented the pre-rename `minimal`
binary surface) with an overview page routing between the two planes
and four binaries, plus per-binary pages generated from --help at
e5ce5fb:

- cli.md: two-plane intro, binary table, platform availability notes
  (macOS ships min+minvmd only; mip run is Linux-only), pointer to the
  in-sandbox helpers in sandbox-operations.md
- cli-mip.md: package/build CLI; absorbs the old cli.md command
  content under the correct binary name, and notes that
  MINIMAL_SCIENCE_MODE-hidden commands are undocumented (refs #821,
  #822)
- cli-min.md: session CLI, including the git-remote-min helper flow
  (`git push min://<session>`) and a note that mesh/ssh-forward exist
  only behind the off-by-default remote-access cargo feature
- cli-minimald.md: ops page for the host daemon (refs #820)
- cli-minvmd.md: ops page for the VM daemon, including the new
  `config show|set` subcommands (refs #823)

Inbound links in sandbox-operations.md, minimal-dot-toml.md, tasks.md,
and linux-host-setup.md pointed at /reference/cli anchors that moved;
repoint them at ./cli-mip.md / ./cli.md with relative links and the
corrected `mip` command names.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The mip dep long_about showed --input_deps_depth (underscore spelling)
and a -p flag that does not exist on dep; minimald's --detach and
--gvproxy-bin help referenced the retired `minimal` CLI name and
internal DM2 jargon.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Add docs/internal/proposals/ with the needs-human CI artifacts for the
OSS docs launch. The workflow layer is frozen and CODEOWNER-gated, so
nothing here is wired into CI; a code owner applies each piece through
review:

- docs-site.yml: complete draft of the docs-site lane on the repo's
  lane pattern (always-triggered, in-workflow paths filter, if-always
  docs-site-success aggregator), with a weekly advisory online link
  sweep and a disabled Pages deploy job.
- ci-yml-docs-filter.patch: extend ci.yml's code negation filter with
  the docs-site toolchain files and NOTICE; widen !LICENSE to
  !LICENSE*. Verified with git apply --check.
- promote-yml-webapp-repoint.patch: retarget the post-promotion docs
  dispatch from the deprecated gominimal/docs to gominimal/webapp.
  Verified with git apply --check.
- webapp-reference-sync.yml: draft workflow for gominimal/webapp that
  consumes the dispatch, mirrors the manifest-listed reference pages,
  and drift-checks weekly.
- README.md: index, freeze rationale, apply instructions, follow-up
  checklist.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Add lane self-inclusion to the docs filter, prune manifest-dropped
pages in the webapp sync job, and note the link-normalization
prerequisite in the apply instructions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Add a VitePress 1.6.4 site rooted at docs/: exact-pinned npm toolchain
(package.json, package-lock.json, .nvmrc), site config with strict
dead-link checking (ignoreDeadLinks: false), srcExclude fencing for
specs/, spikes/, internal/, and session-domain-diag.md, and mermaid
rendering via vitepress-plugin-mermaid.

The theme ports the historical gominimal/docs design tokens: monochrome
palette, zero border-radius, 1px borders, uppercase mono headings, and
self-hosted Space Grotesk via @fontsource. The AstroMono @font-face
block is present but commented out pending font license verification.
Brand marks and the favicon are fetched from the historical docs repo
into docs/public/.

New pages: a home page (hero wording is a launch-decision placeholder)
and thin wrappers under docs/arch/ embedding
crates/sessions/docs/COMPOSITION.md and crates/minvmd/README.md via
VitePress includes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Replace site-absolute links in docs/reference with forms that resolve
both on GitHub and in the VitePress build, which now fails on dead
links:

- /reference/... links become relative ./page.md links.
- Dead /concepts/... links point at their live counterparts on
  https://docs.minimal.dev.
- ci-strategy.md's ../CONTRIBUTING.md link becomes a GitHub blob URL,
  since the file sits outside the site root.

Also guard two spots that broke Vue compilation of the strict build:
wrap raw Rust generics in rust-coding-standards.md in code spans, and
v-pre the inline GitHub Actions expression in ci-strategy.md so it is
not parsed as a Vue interpolation (which truncated the rendered page).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Cover the session/VM plane (min -> minimald -> minvmd, composition,
networking, persistence, remote cache) alongside the existing build
plane, add a full 28-crate map and a platform matrix, and fix the
minimal.toml discovery description: the search walks up toward the
filesystem root, not down.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Add docs/specs/README.md indexing specs 01-09 with a defined status
vocabulary (planned | shipped | superseded), and flip frontmatter
status from planned to shipped in all 14 frontmatter-bearing spec
files: the features of 01-03 and 05-09 are verified in-tree, and 04
is implemented (ot has the render-free core with new_root/snapshot/
changed, indicatif_shim.rs with render_operations_while, and minimald
has channel_progress.rs). Companion architecture files match their
spec.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Add docs/spikes/README.md (dated index with question/outcome) and
docs/decisions/README.md (ADR conventions and index; 0001 keeps its
filename so the rust-coding-standards link stays valid). Move
docs/session-domain-diag.md to docs/internal/ and update the seven
inbound references in specs 01 and 02. Add docs/internal/README.md
indexing the internal corpus and noting that docs/specs and
docs/spikes are excluded from the docs site but publicly visible.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Replace personal names in ADR 0001 decider/sign-off lines with
"project maintainers", drop the bot author field from both spike
frontmatter blocks, rephrase the spec-01 open question so it no
longer assigns confirmation to an issue owner, and remove the
retired sdd:triage label reference from the spec-03 architecture
notes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Describe the current release and install flow end to end: release.yml
(verify-ci gate on the five lane aggregators, build/sign jobs, staging
into the immutable versions/<sha>/ bucket layout, the unstable channel
auto-flip, and the legacy minimal-shim archive upload), nightly.yml's
daily cut + shipped-artifact smoke + nightly blessing, promote.yml's
gated stable promotion and docs dispatch, prune-releases.yml, the
install.sh resolution chain and per-platform component sets, and a
short operator runbook.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Carries forward the old README's 8-core/16GB build recommendation and
notes the minvmd-linux-amd64 binary attached to GitHub Releases.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Tool-neutral orientation doc at the repo root: two-plane overview and the
four binaries, the 28-crate map, the platform matrix (macOS scoping and
why), system dependencies, a grouped index of all 19 justfile recipes,
verified footguns with sources, the 11-workflow CI lane map with the five
required-check aggregators, and the conventions/hard-rules summary.

Mark CONTRIBUTING.md's pre-PR command block as the canonical copy and
cross-link AGENTS.md's macOS-scoped variants, so the commands live in
exactly one place.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Everything the old CLAUDE.md carried directly or via @-includes (commit
conventions, architecture, Rust standards, the CI-freeze rule) is now
reachable through AGENTS.md, which CLAUDE.md includes. Only the
Claude-workflow-specific iteration and finish-command notes remain.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- min --help no longer shows the flattened GlobalArgs doc comment
  ("Shared arguments all subcommands") as the top-level description:
  the struct comment is demoted to a regular comment and the Cli
  command gets an explicit about identifying the session CLI.
- min login long_about: drop the stale `minimal login` spelling and
  render the curl example verbatim instead of clap re-wrapping it
  onto one line.
- min completions long_about: "the minimal CLI" -> "the min CLI".
- mip cache clean and its --older-than flag now carry help text
  describing the actual behavior (retention cutoff, always-kept
  task/stack packages, stale sandbox/task/temp dir cleanup, and the
  d/h/m duration forms) instead of rendering blank.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…eatures

Audit of docs/reference/ against the code:

- cli.md: Linux installs ship min/mip/minimald only; minvmd is a
  source build (prebuilt amd64 attached to GitHub Releases, no arm64)
  — per scripts/stage-release.sh COMPONENTS and release-pipeline.md.
- minimal-dot-toml.md: rename stale `minimal update`/`minimal
  materialize` to the mip CLI, and cross-reference that `mip update`
  rewrites the upstream and sideload locked_commit fields in place
  (crates/op/src/project/update.rs).
- tasks.md: mip run in the args example; document `description`
  (shown by mip status), the /bin/<cmd> exec resolution, arg defaults
  making arguments optional, and the full arg datatype forms (arrays,
  enums, table form with help/default) per the args crate.
- build-specs.md: replace the line-anchored stdlib blob link with a
  stable file link; tests run by `mip check`.
- harness-specs.md: `mip build` / `mip init` binary names (light
  re-audit after #813).
- sandbox-operations.md: match the in-sandbox helper
  (crates/mctx/src/min_helper.sh + env.rs): --session flag and
  no-flag default, stack.* not harness.* targets, check takes
  --stacks (not --harnesses) and has no --skip-checkers/short flags,
  add the build/test shorthands and patched-pkg, mark the surface
  Linux-only, and add a note disambiguating the helper from the min
  session CLI.
- cli-min.md, cli-mip.md: regenerate the snippets touched by the help
  text fixes (cache clean, login example) from the rebuilt binaries
  at d9f2016.
- crates/minvmd/README.md: replace the stale "persistent data disk is
  a follow-up" note with the shipped per-VM /dev/vdb ext4 volume
  (crates/minvmd/src/volume.rs, spec 08) and update the libkrun
  guidance for the pinned source build (#694), keeping brew as the
  local-dev fallback.
- frontmatter: every reference page now carries title + description.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

List the nine user-reference pages the webapp reference-sync workflow
(docs/internal/proposals/webapp-reference-sync.yml) mirrors, in the
agreed {"pages": [...]} shape with filenames relative to
docs/reference/. The ops pages (cli-minimald.md, cli-minvmd.md) are
deliberately not exported.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Four materialize examples still used the retired minimal spelling;
sandbox-operations documented a --task <name> form the helper does not
implement (Refs: #834); linux-host-setup and cli.md wording aligned
with the shipped binaries.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The justfile rework (c917d35) replaced the dm1/dm2/dm3 vocabulary with
up/up-kvm/down and grew the recipe set from 19 to 32, folding the CI
gates (ci, test, test-ignored, clippy, deny, fmt, doctest) and the e2e /
VM harnesses (e2e, e2e-native, test-vm, test-root-integration,
test-lifecycle, soak, reap) into just. Rewrite the AGENTS.md recipe
index against the actual recipes, re-source every footgun that cited
the old recipe names (READY-timeout exports now live in the justfile
header; leaked-VM reaping is 'just reap'; codesign-minvmd is gone), and
make 'just ci' the pre-PR headline, deferring to CONTRIBUTING.md as
canonical with the macOS test-cross and VM-path extras. Also fold the
R2 read-path canary into the ci lane one-liner.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

main gained the min bug host diagnostic bundle command (f4e0491) and a
shared resource-pool header in the session listing (cfeafc7). Add the
bug section — bundle layout, failure-isolated manifest, the no-mutation
guarantee, and the env-value allowlist redaction policy — note the
RESOURCE POOL header under ls, and bump the generated-at marker to the
merged tree. dirs and session are unchanged on the surface (the dirs
rework was an internal refactor feeding the bug bundle).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CI (repo-wide lane) and license badges, per the badge conventions of
prominent Rust and sandbox projects; logo follows the firecracker/libkrun
theme-aware <picture> pattern.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Light mode via mermaid base theme variables (no more default yellow);
dark mode via .dark-scoped CSS overrides, since the plugin forces
mermaid's dark theme and a second themeVariables set can't be supplied.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The code moved to stacks (stacks/<name>/stack.ncl, [stack] section,
mip check --stacks); [harness] survives only as a deprecated serde
alias and stays documented as such. Test-harness senses untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Documents the loadout TOML schema, discovery under
<config>/minimal/loadouts/, activation flags and default selection,
client config, and composition/conflict semantics — with a callout
that patches and lifecycle hooks compose but are not yet applied.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Local mac builds fetch the guest kernel/rootfs via
scripts/fetch-prebuilt.sh (content-addressed cache fetch; just
artifacts wraps it) and no longer call into minimal for minvmd
components.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

From the issue #695 working session, each claim re-verified in code:
bake-at-activation semantics, spawn-time no-such-package failure,
warn-drop on missing patch sources, the NameMismatch error, and a
compact 'Vars in the attach shell' section (bash --noprofile -l,
PS1 override, once-only PROMPT_COMMAND banner).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Adopt PR 836's single-license decision everywhere: drop the dual
MIT-OR-Apache-2.0 texts (canonical text is the root LICENSE), restate
NOTICE as Apache-2.0-only while keeping the libkrun/gvproxy
attributions, flip the workspace license field, and rewrite the
internal licensing stance (LGPL dependency exceptions unchanged).
cargo deny check licenses passes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…idance

min add has no --session flag — the quickstarts now write the
[session] block of minimal.toml directly. Fill the Loadout section
(was TBD) from the new reference page, add the macOS build-scope
caveat, renumber the CONTRIBUTING TL;DR, and align the workflow's
commit-message step with the enforced Conventional Commits rule.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Code-owner application of the drafts under docs/internal/proposals/:
add .github/workflows/docs-site.yml (VitePress build, docs/reference
site-absolute link guard, offline lychee check, rendered-site
artifact; Pages deploy job present but if:false; docs-site-success
aggregator, not yet a required check), extend ci.yml's code negation
filter so docs-toolchain and attribution paths (LICENSE*, NOTICE,
package.json, package-lock.json, .nvmrc) skip the Rust lanes, and
repoint promote.yml's reference-docs-promoted dispatch from the
deprecated gominimal/docs to gominimal/webapp. Remove the applied
proposals directory and reconcile the release-pipeline and AGENTS
workflow references.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Pull in the base branch's 'Merge main' commit. Clean auto-merge —
oss/integration already contains all of main and 836's content, so
the new merge commit introduces no textual conflicts; README and
CONTRIBUTING are unchanged from oss/integration's reviewed versions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…uler)

Address CodeRabbit (Major): the docs-site workflow inlined the build +
link-check logic, violating the repo's own CI contract (CONTRIBUTING.md /
docs/ci-strategy.md: workflows are thin schedulers over tests, scripts/,
and the justfile). Extract build, the site-absolute-link guard, and the
offline/online lychee checks into scripts/docs-check.sh (modes:
build|links|all|online-links) with a 'just docs-check' recipe; reduce
docs-site.yml to toolchain install + script calls + artifact upload. All
gating, concurrency, the advisory sweep, the disabled deploy, and the
docs-site-success aggregator are preserved.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>