chore: sync template files and configuration

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: Jonathan D.A. Jewell

CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+#### CLI Features (SHOULD - P2)
+- `vordr doctor` command with 5 check categories (runtime, networking, kernel, state, gatekeeper)
+- `vordr system df/prune/info/reset` commands with dry-run support
+- `vordr compose up/down/ps/logs/config` with explicit unsupported key warnings
+- `vordr login/logout` with registry authentication
+- `vordr auth ls` for credential management
+- `vordr completion bash|zsh|fish` for shell completions
+
+#### CLI Features (COULD - P3)
+- `vordr profile ls/show/diff/set-default/create` for security profile management
+- `vordr explain` command for policy rejection diagnostics
+- Three built-in security profiles: strict, balanced, dev
+
+#### Documentation
+- `docs/troubleshooting.adoc` - Top 20 failure modes with doctor integration
+- `docs/mental-model.adoc` - Minimal user guide (under 2 pages)
+- `docs/surface-contract.adoc` - API stability contract with exit codes
+
+#### Quality Assurance
+- `CHECKLIST-QOL.adoc` - QoL completion checklist with ratings
+- `EVALUATION-REPORT.adoc` - Veridical evaluation template
+- JSON schemas for CLI output (`spec/schemas/*.v1.json`)
+- Spec version pinning (`spec/SPEC_VERSION`)
+
+#### CI/CD
+- `doctor-smoke.yml` - Doctor command smoke tests
+- `e2e-readme.yml` - README happy path tests
+- `schema-lint.yml` - JSON schema validation
+- `surface-contract-lint.yml` - Surface change detection
+- `conformance-consumer.yml` - Spec conformance tests
+- `release.yml` - Multi-platform release with SBOM and provenance
+
+#### Developer Experience
+- PR template with surface/seam impact checkboxes
+- Evidence directory for evaluation artifacts
+
+### Changed
+- Exit codes now follow documented taxonomy (see `docs/surface-contract.adoc`)
+
+### Fixed
+- Doctor command JSON output now matches schema
+
+## [0.1.0] - Unreleased
+
+### Added
+- Initial Vordr container engine implementation
+- Container lifecycle: create, start, stop, pause, resume, kill, delete
+- OCI runtime integration (youki/runc)
+- Netavark networking backend
+- SQLite state management with WAL mode
+- Gatekeeper FFI stub for SPARK integration
+- Registry client with auth support
+- MCP server for AI-assisted management

CONTRIBUTING.md

@@ -0,0 +1,116 @@
+# Clone the repository
+git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git
+cd {{REPO}}
+
+# Using Nix (recommended for reproducibility)
+nix develop
+
+# Or using toolbox/distrobox
+toolbox create {{REPO}}-dev
+toolbox enter {{REPO}}-dev
+# Install dependencies manually
+
+# Verify setup
+just check   # or: cargo check / mix compile / etc.
+just test    # Run test suite
+```
+
+### Repository Structure
+```
+{{REPO}}/
+├── src/                 # Source code (Perimeter 1-2)
+├── lib/                 # Library code (Perimeter 1-2)
+├── extensions/          # Extensions (Perimeter 2)
+├── plugins/             # Plugins (Perimeter 2)
+├── tools/               # Tooling (Perimeter 2)
+├── docs/                # Documentation (Perimeter 3)
+│   ├── architecture/    # ADRs, specs (Perimeter 2)
+│   └── proposals/       # RFCs (Perimeter 3)
+├── examples/            # Examples (Perimeter 3)
+├── spec/                # Spec tests (Perimeter 3)
+├── tests/               # Test suite (Perimeter 2-3)
+├── .well-known/         # Protocol files (Perimeter 1-3)
+├── .github/             # GitHub config (Perimeter 1)
+│   ├── ISSUE_TEMPLATE/
+│   └── workflows/
+├── CHANGELOG.md
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md      # This file
+├── GOVERNANCE.md
+├── LICENSE
+├── MAINTAINERS.md
+├── README.adoc
+├── SECURITY.md
+├── flake.nix            # Nix flake (Perimeter 1)
+└── justfile             # Task runner (Perimeter 1)
+```
+
+---
+
+## How to Contribute
+
+### Reporting Bugs
+
+**Before reporting**:
+1. Search existing issues
+2. Check if it's already fixed in `{{MAIN_BRANCH}}`
+3. Determine which perimeter the bug affects
+
+**When reporting**:
+
+Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include:
+
+- Clear, descriptive title
+- Environment details (OS, versions, toolchain)
+- Steps to reproduce
+- Expected vs actual behaviour
+- Logs, screenshots, or minimal reproduction
+
+### Suggesting Features
+
+**Before suggesting**:
+1. Check the [roadmap](ROADMAP.md) if available
+2. Search existing issues and discussions
+3. Consider which perimeter the feature belongs to
+
+**When suggesting**:
+
+Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include:
+
+- Problem statement (what pain point does this solve?)
+- Proposed solution
+- Alternatives considered
+- Which perimeter this affects
+
+### Your First Contribution
+
+Look for issues labelled:
+
+- [`good first issue`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks
+- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed
+- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements
+- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/perimeter-3) — Community sandbox scope
+
+---
+
+## Development Workflow
+
+### Branch Naming
+```
+docs/short-description       # Documentation (P3)
+test/what-added              # Test additions (P3)
+feat/short-description       # New features (P2)
+fix/issue-number-description # Bug fixes (P2)
+refactor/what-changed        # Code improvements (P2)
+security/what-fixed          # Security fixes (P1-2)
+```
+
+### Commit Messages
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]

MVP.adoc

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: PMPL-1.0 OR PMPL-1.0-or-later
+= Svalinn MVP Checklist
+:toc: preamble
+:toclevels: 2
+
+This checklist scopes the MVP to a single-image CI pipeline with a policy gate
+and single-node scheduling.
+
+== MVP Targets
+
+* Single signer + single transparency log
+* Policy gate requires signer match + required predicates
+* Single-node scheduling only (local host)
+
+== Required Deliverables
+
+=== 1. Gateway API (ReScript/Deno)
+
+* [ ] `POST /verify` to validate a bundle against trust store + policy
+* [ ] `POST /run` to schedule and start a container after verification
+* [ ] JSON responses using `error-response.v1.json`
+* [ ] MVP gateway: `tools/mvp/svalinn_gateway.ts`
+
+=== 2. Gatekeeper Policy
+
+* [ ] Implement schema `spec/schemas/gatekeeper-policy.v1.json`
+* [ ] Load policy from file and enforce:
+  - required predicate types
+  - allowed signer key IDs
+  - log quorum (set to `1` for MVP)
+* [ ] MVP policy example at `spec/policy/mvp-policy.json`
+* [ ] MVP verifier helper in `tools/mvp/svalinn_gate.py`
+
+=== 3. Single-Node Scheduling
+
+* [ ] FIFO queue for pending containers
+* [ ] Local-only placement (no multi-node logic)
+* [ ] Simple status model: queued, starting, running, failed, stopped
+* [ ] MVP queue stub in `tools/mvp/svalinn_gateway.ts`
+
+=== 4. Vordr Delegation
+
+* [ ] Translate request to Vordr CLI or API
+* [ ] Capture execution metadata for audit logs
+* [ ] MVP CLI delegation from `tools/mvp/svalinn_gateway.ts`
+
+== Deferred to 1.0
+
+* Multi-log quorum enforcement (>=2)
+* Threshold signatures
+* Multi-node scheduling and service discovery
+* Authn/authz and rate limiting

docs/cli-ux-compat.adoc

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: PMPL-1.0 OR PMPL-1.0-or-later
+= CLI UX Compatibility Rules
+:toc: preamble
+:toclevels: 2
+
+This document defines command and flag compatibility goals with Docker, Podman,
+and nerdctl to reduce user friction.
+
+== 1. Command Parity (MVP)
+
+Implement (or alias) these commands with the same semantics:
+
+* `run`, `ps`, `stop`, `rm`, `pull`
+* `image ls` (alias `images`)
+* `logs`, `inspect`
+* `login`, `logout`
+
+== 2. Flag Compatibility (MVP)
+
+For `vordr run`, accept and preserve the common flags:
+
+* `-d`, `--detach`
+* `--rm`, `--remove-on-exit` (prefer new flag; accept old for migration)
+* `--name <name>`
+* `-p`, `--publish <host:container>`
+* `-e`, `--env <KEY=VALUE>`
+* `-v`, `--volume <host:container>`
+* `--network <name>`
+* `--pull <policy>`
+* `--entrypoint <cmd>`
+* `-w`, `--workdir <path>`
+* `-u`, `--user <uid[:gid]>`
+* `--read-only`
+* `--tmpfs <path>`
+* `--cap-add <cap>`, `--cap-drop <cap>`
+
+== 3. Argument Ordering Rules
+
+* Flags are order-independent.
+* Repeated flags append (e.g., multiple `-e` or `-v`).
+* Accept both `--flag value` and `--flag=value`.
+* Allow `--` to separate run command arguments.
+
+== 4. Migration Rules
+
+* If a Docker/Podman flag is unsupported, emit:
+  - `ERR_USAGE` with a short explanation
+  - a replacement suggestion when available
+* Preserve exit codes as defined in `docs/surface-contract.adoc`.
+* Keep `--rm` as a deprecated alias of `--remove-on-exit` until v1.0.
+
+== 5. 1.0 Parity Goals
+
+* `exec`, `stats`, `top`
+* `network ls/create/rm`
+* `volume ls/create/rm`
+* `system df/prune`