Add installer research report and installer/onboarding specification

[peternicholls]

Motivation

• Reduce onboarding friction by defining a recommended install path, idempotent first-run setup, and project initialization flows for StackLane.
• Capture industry best-practices for installer distribution, integrity checks, least-privilege operations, and guided machine-readable setup semantics.
• Specify new CLI surfaces (stacklane setup, stacklane init, stacklane doctor) and a support/compatibility matrix to improve first-run reliability and recovery.

Description

• Add a research report at docs/installer-research-report.md that summarizes installer patterns, recommended UX, and a phased implementation roadmap.
• Add a formal feature specification at specs/005-installer-and-onboarding/spec.md that includes user stories, acceptance tests, functional and non-functional requirements, entities, and success criteria.
• Define concrete requirements for new commands including normalized statuses (ready/needs_action/error), --json machine-readable output, idempotency, non-silent privilege escalation, and release integrity guidance.
• Recommend package strategy (Homebrew primary on macOS, signed-binary fallback), post-install caveats, and a prioritized implementation plan spanning setup, doctor, init, and future TLS work.

Testing

• No automated tests were run as part of this change because the PR adds specification and documentation only.
• The files contain explicit independent test scenarios and acceptance criteria to drive subsequent implementation and automated tests.

---

Codex Task

[Copilot]

Pull request overview

Adds documentation artifacts to guide future implementation of a first-run installer/onboarding experience for Stacklane, including new CLI surfaces (setup, doctor, init) and a readiness/status reporting contract.

Changes:

• Added a formal feature spec with user stories, requirements, and success criteria for installer/onboarding/readiness commands.
• Added an installer research report summarizing industry patterns and a phased roadmap for distribution + onboarding UX.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
specs/005-installer-and-onboarding/spec.md	New feature specification defining user stories, requirements, and success criteria for setup/doctor/init onboarding.
docs/installer-research-report.md	New research report capturing recommended installer/distribution patterns and an implementation roadmap.

[Copilot]

The product brand is established elsewhere in the repo as “Stacklane” (e.g., specs/002-project-rebrand/spec.md and README.md), but this spec uses “StackLane” in headings and scenarios. Please standardize to “Stacklane” throughout (reserving “StackLane” only when explicitly referring to the GitHub repository name).

[Copilot]

This spec introduces stacklane init as creating .env.stacklane when absent, but the current runtime contract already says stacklane up/stacklane attach write a starter .env.stacklane automatically when missing (docs/runtime-contract.md). Please clarify the intended contract: what additional behavior init provides vs the existing auto-starter behavior, and whether up/attach should continue writing the starter file or delegate that responsibility to init.

Suggested change

	A developer in a project root wants an optional guided initializer that creates project-local StackLane config and links the app cleanly to the stack contract.
	**Why this priority**: First machine setup and first project setup are separate concerns; project onboarding needs a safe, repeatable entrypoint.
	**Independent Test**: In a repository without `.env.stacklane`, run `stacklane init` from project root and confirm it writes a starter config, validates docroot/site settings, and provides next commands.
	**Acceptance Scenarios**:
	1. **Given** a project root without `.env.stacklane`, **When** the operator runs `stacklane init`, **Then** StackLane creates a starter project config with documented defaults and ownership boundaries.
	2. **Given** a project with custom app layout, **When** the operator runs `stacklane init --docroot <path> --site-name <name>`, **Then** the written config preserves those values and validates them against project paths.
	3. **Given** a project already initialized, **When** the operator reruns `stacklane init`, **Then** StackLane does not overwrite existing settings unless an explicit overwrite flag is provided.
	## Operational Impact *(mandatory)*
	### Ease Of Use & Workflow Impact
	- Affected commands: new `stacklane setup`, new `stacklane doctor`, new optional `stacklane init` (project-root), existing `stacklane dns-setup`, and first-run documentation.
	- Backward compatibility: existing lifecycle commands (`up`, `attach`, `status`, `down`) remain unchanged; this feature adds onboarding/readiness surfaces.
	- Friction removed: manual prerequisite discovery, unclear remediation steps, and inconsistent first-run command order.
	A developer in a project root wants an optional guided initializer that creates or updates project-local StackLane config, validates project-specific settings, and links the app cleanly to the stack contract.
	**Why this priority**: First machine setup and first project setup are separate concerns; project onboarding needs a safe, repeatable entrypoint without changing the existing lifecycle fallback behavior.
	**Independent Test**: In a repository without `.env.stacklane`, run `stacklane init` from project root and confirm it writes the same starter project-local config shape used by the runtime, validates docroot/site settings, and provides next commands.
	**Acceptance Scenarios**:
	1. **Given** a project root without `.env.stacklane`, **When** the operator runs `stacklane init`, **Then** StackLane creates a starter `<project>/.env.stacklane` with documented defaults, ownership boundaries, and immediate validation/next-step guidance.
	2. **Given** a project with custom app layout, **When** the operator runs `stacklane init --docroot <path> --site-name <name>`, **Then** the written config preserves those values and validates them against project paths before recommending the next lifecycle command.
	3. **Given** a project already initialized, **When** the operator reruns `stacklane init`, **Then** StackLane does not overwrite existing settings unless an explicit overwrite flag is provided, while existing `stacklane up`/`stacklane attach` behavior continues to auto-write only a starter `<project>/.env.stacklane` when the file is absent.
	## Operational Impact *(mandatory)*
	### Ease Of Use & Workflow Impact
	- Affected commands: new `stacklane setup`, new `stacklane doctor`, new optional `stacklane init` (project-root), existing `stacklane dns-setup`, and first-run documentation.
	- Backward compatibility: existing lifecycle commands (`up`, `attach`, `status`, `down`) keep their current runtime behavior, including auto-writing a starter `<project>/.env.stacklane` when absent; `stacklane init` adds an explicit guided onboarding path rather than taking over that bootstrap responsibility.
	- Friction removed: manual prerequisite discovery, unclear remediation steps, inconsistent first-run command order, and lack of a dedicated project-initialization flow with validation.

[Copilot]

Success Criteria SC-004 states docs should present the sequence as install -> setup -> init -> up, but earlier requirements describe stacklane init as optional (FR-016) and also give examples like setup then up (FR-015). Please reconcile this so the spec consistently treats init as conditional/optional (e.g., only when .env.stacklane is missing or when guided validation is desired).

Suggested change

	- **SC-004**: Documentation consistently presents the onboarding sequence as `install -> setup -> init -> up` and includes integrity verification for direct binary installs.
	- **SC-005**: In repos without StackLane project config, operators can run `stacklane init` and reach a valid `.env.stacklane` configuration with no manual file authoring.
	- **SC-004**: Documentation consistently presents the onboarding sequence as `install -> setup -> [init if needed] -> up`, with `stacklane init` positioned as a conditional step for repos missing `<project>/.env.stacklane` or when guided validation/scaffolding is desired, and includes integrity verification for direct binary installs.
	- **SC-005**: In repos without project-local StackLane config at `<project>/.env.stacklane`, operators can run `stacklane init` and reach a valid `<project>/.env.stacklane` configuration with no manual file authoring.

[Copilot]

The product brand is generally “Stacklane” across maintained docs (e.g., README.md header), but this report uses “StackLane” throughout. Please standardize capitalization to match the established “Stacklane” branding, reserving “StackLane” only for the GitHub repo name where needed.

[Copilot]

The packaging strategy section says “Homebrew formula/cask”, but the Stage 0 example hard-codes brew install stacklane (formula-style). Please align the example with the intended packaging choice (formula vs cask) or present both explicitly so operators don’t follow the wrong command.

Suggested change

	- `brew install stacklane` (or signed binary script).
	- Homebrew formula: `brew install stacklane`
	- Homebrew cask: `brew install --cask stacklane`
	- Or use the signed binary install script.

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive research report and a formal feature specification for improving the StackLane installer and onboarding experience. The proposed changes outline the introduction of stacklane setup, stacklane doctor, and stacklane init commands to provide a guided, idempotent, and diagnostic-friendly environment setup. The review feedback identifies several opportunities to strengthen the specification, including aligning functional requirements with the research findings (specifically regarding OS/architecture checks and port collision detection), resolving contradictions in the recommended onboarding sequence, and clarifying technical implementation details such as JSON output streams and exit code semantics for automation.

[gemini-code-assist]

There is a potential conflict between the proposed stacklane init command and the existing behavior described in the README.md. The current README.md (line 114) states that stacklane up automatically writes a starter .env.stacklane file if it is missing. If init is introduced as the recommended path for project initialization, the automatic generation in up should likely be deprecated or modified to suggest running init instead, to ensure users benefit from the guided setup logic.

[gemini-code-assist]

FR-006 specifies checks for Docker binary presence and daemon reachability, but it omits the OS and architecture compatibility checks mentioned in the research report (Section F, line 155). To ensure a robust preflight, stacklane setup should also validate that the host environment matches the supported platform matrix.

Suggested change

	- **FR-006**: Setup MUST include Docker binary presence and daemon reachability checks.
	- **FR-006**: Setup MUST include OS/architecture compatibility, Docker binary presence, and daemon reachability checks.

[gemini-code-assist]

FR-010 defines the scope of stacklane doctor checks but misses "port conflicts," which is explicitly listed as a requirement in the research report (Section G, line 173). Port collision detection is a common source of drift in local development environments and should be included in the formal specification.

Suggested change

	- **FR-010**: `stacklane doctor` MUST include checks for binary/version visibility, Docker readiness, DNS readiness, shared gateway health, and writable state directories.
	- **FR-010**: `stacklane doctor` MUST include checks for binary/version visibility, Docker readiness, DNS readiness, shared gateway health, port conflicts, and writable state directories.

[gemini-code-assist]

FR-011 mentions --json support but does not specify the output stream. For CLI tools intended for automation, it is a best practice to emit machine-readable data to stdout while keeping logs and diagnostic messages on stderr. This ensures that piping output to tools like jq works as expected.

Suggested change

	- **FR-011**: Both setup and doctor MUST support machine-readable output via `--json` with stable step identifiers.
	- **FR-011**: Both setup and doctor MUST support machine-readable output via `--json` to `stdout` with stable step identifiers.

[gemini-code-assist]

The term "blocking readiness issues" in FR-012 is ambiguous. It should be clarified whether a status of needs_action (which implies a fix is required but not yet an error) triggers a non-zero exit code. Usually, any state other than ready should result in a non-zero exit for a readiness check command.

[gemini-code-assist]

The next-step guidance in FR-019 (setup as needed, then up) contradicts the canonical onboarding sequence defined in the research report (Stage 2, line 188 and Section 229), which places setup before init. If setup is a machine-wide prerequisite, init should assume it has already been run or verify it, rather than suggesting it as a follow-up step.