Platform Support Policy & Roadmap Freshness

Status: Open — design proposal

Problem

Two documentation and process gaps:

No declared platform support matrix. Only 2 #[cfg(windows)] blocks vs 30+ #[cfg(unix)] in the codebase. CI ships macOS and Linux binaries only. Windows is effectively unsupported, but the docs never say so. The next user who tries cargo install jackin on Windows hits cryptic errors with no landing page.
Roadmap staleness is invisible. The roadmap is at 88+ items. No audit catches staleness. An item marked Status: Open could be untouched for 18 months. "Open" without a date is misleading.

Proposal

Part 1 — Platform support policy page

Write a contributor-facing reference page (docs/content/docs/reference/platform-support.mdx) declaring:

Platform	Status
macOS (aarch64, latest)	Primary — all development and verification happens here
macOS (x86_64, latest)	Supported (via CI)
Linux (aarch64, x86_64)	Experimental — community-tested, no in-house test machine today. Will become a priority when jackin' moves to server-side use cases (Kubernetes, remote operation). Community contributions and bug reports welcome.
Windows (WSL2)	Best-effort — uses the Linux build. No dedicated testing.
Windows (native)	Out of scope — jackin's TUI/PTY model relies on Unix primitives.

Philosophy: jackin' targets the latest versions of everything (latest Debian for the construct image, latest macOS, latest OrbStack). No intention to support older versions. To change this stance, the project needs at least one strong advocate who uses jackin' on that platform and can explain why.

Part 2 — Base image rationale

Document why the construct image uses Debian only (latest debian:trixie): it's the most well-known and predictable base image in the Docker ecosystem, stable, not fragmented. No Alpine or slim variants are planned until a strong advocate appears with a clear use case. This is not a roadmap item for implementation — it's a policy statement.

Part 3 — Roadmap freshness tracking

Add last_reviewed: YYYY-MM-DD frontmatter to every roadmap MDX file. Add docs/scripts/check-roadmap-freshness.ts that runs in CI and as bun run check:roadmap-freshness:

Flags items with last_reviewed > 6 months as stale.
Reports them in the CI output.
The script is ~30 lines of TypeScript.

Apply last_reviewed: 2026-06-02 to every existing roadmap MDX as a baseline. New roadmap items should include the field from creation.

Non-goals

Do not add WSL2 first-class support — that requires dedicated testing.
Do not add Alpine/slim construct image variants — no advocate or use case exists.
Do not archive stale roadmap items. Freshness tracking is sufficient; old items stay.
Do not auto-open GitHub issues for stale items — just report in CI.

Should the platform support page live under reference/ or under getting-started/?
What is the staleness threshold? 6 months is suggested but adjustable.
Should the freshness script also check for items missing the last_reviewed field entirely?