docs(onboarding): make deploy/compose the primary onboarding path #109

Activity

1. PeterGuy326

   added

   type:featureA new user-facing capabilityA new user-facing capability

   priority:p1Important after the immediate critical pathImportant after the immediate critical path

   on Aug 29, 2026
2. waterbro-8 commented on Aug 30, 2026

   

   waterbro-8

   on Aug 30, 2026

   Collaborator

   More actions

   裁决摘要（技术 P9）

   REQ-003 拆,不砍:已按 requirement-decision.v1 移入新 issue #112(mem doctor / first-run 指引面)。#109 收窄为纯文档 issue。取证基线:main @ 419a420。

   schemaVersion: requirement-decision.v1
   canonicalIssue: "https://github.com/fullstack-ai-infra/mem/issues/109"
   previousRevision: R1
   resultingRevision: R2
   decisionType: narrowing
   oldDecision: "technicalOwner=unassigned; requirements=[REQ-001 docs repositioning, REQ-002 bare-metal demotion with WSL/Linux equivalence, REQ-003 doctor/first-run guidance pointing at the container path]; acceptanceCriteria=[AC-001, AC-002, AC-003 first-time messaging fixture]; openDecision='whether doctor-level container-path detection belongs here or in a shared doctor surface'"
   newDecision: "technicalOwner=@waterbro-8 (independent reviewer @PeterGuy326 or @Bindy-lbb); requirements=[REQ-001, REQ-002]; acceptanceCriteria=[AC-001, AC-002]; REQ-003 and AC-003 move verbatim to https://github.com/fullstack-ai-infra/mem/issues/112 at R1, which this issue now names as a non-blocking downstream dependency; the shared-doctor-surface question is answered there as 'shared surface, own issue'; the record is retyped docs-only (type:docs, area:docs)."
   reason: "REQ-003 asked for a CLI surface that does not exist anywhere in this repository: the strings 'doctor' and 'first-run' have zero occurrences at main @ 419a420, so it is net-new Go code with its own output contract and tests. Mixing it into a README/onboarding rewrite breaks the readiness gate rule that an issue be small enough for one reviewable PR or be split into linked issues (docs/maintainers/triage.md), and it is why this docs-repositioning issue still carries type:feature."
   impact: "#109 becomes a documentation-only change that can be validated by reading the rendered tree, unblocked by any code work. Nothing is cancelled: first-run guidance still owns an issue, an owner, requirements and ACs at #112, at P2, and #112 depends on this issue rather than the reverse, so the P1 docs delivery cannot be gated by the P2 CLI surface."
   approver: "@PeterGuy326"
   decidedAt: "2026-08-30T06:17:00Z"

   Owner

   • technicalOwner: "@waterbro-8" — owns the docs change and its evidence packet.
   • Independent approval must come from @PeterGuy326 or @Bindy-lbb (.github/CODEOWNERS): AGENTS.md step 6 forbids author self-approval, and the technical owner is the author here.

   What #109 keeps, with the scope sharpened against the actual tree

   Verified so the ACs are checkable rather than aspirational:

   • The premise is confirmed at E2. The bare-metal path is brew-shaped and has no Linux/WSL equivalent written down: docs/RUN_LOCAL.md:24 tells the user to install PostgreSQL + pgvector via brew, and scripts/dev_up.sh:31,117,208 resolve BREW_PREFIX and otherwise die with brew install ... instructions. README.md:181 (开发环境) lists Go 1.25 / Python 3.11 / uv / protoc 34.1 / Docker as prerequisites with no platform notes.
   • The gap is README-level, not deployment-doc-level. docs/DEPLOYMENT.md:99 already documents a "Single-node Compose" profile, and deploy/compose/ carries generate-env.sh plus an eight-service compose.yaml (postgres, redis, minio, minio-init, migrate, worker, memd, web). What is missing is exactly what the ops dogfood hit: README.md:231 快速开始 tells a first-time visitor to run ./scripts/dev_up.sh, i.e. the bare-metal path, and never mentions deploy/compose.
   • Therefore REQ-001's deliverable is a reorder plus one pointer, not a second deployment manual. Rule for the PR: README leads with the container path in a few commands and links docs/DEPLOYMENT.md for the profile detail; duplicating compose prose into README is refused, because the two would drift and DEPLOYMENT.md is the owner of that content.
   • REQ-002's list is now enumerable (so AC-001 is objectively checkable): the brew-shaped steps to give a Linux/WSL equivalent are the PostgreSQL+pgvector install, the MinIO binary fetch, and the setsid/keg-only path resolution in dev_up.sh — with version pins stated per platform, and with the macOS path still first-class (non-goal: no removal of the bare-metal path).

   Suggested labels (needs a maintainer — this account cannot write)

   waterbro-8 has no body/label write rights upstream (PATCH issue and POST labels both 403, admin required). Please @PeterGuy326: retype type:feature → type:docs, add area:docs, add evidence:e2-source (source-level premise above; the ops clean-environment container runbook required by AC-002 is what raises it to E3), and set the lifecycle label once the record is at R2. priority:p1 and the user outcome are unchanged by this revision.

   —— 技术 P9
3. PeterGuy326 commented on Sep 1, 2026

   

   PeterGuy326

   on Sep 1, 2026

   CollaboratorAuthor

   More actions

   schemaVersion: requirement-decision.v1
   canonicalIssue: "https://github.com/fullstack-ai-infra/mem/issues/109"
   previousRevision: R1
   resultingRevision: R2
   resultingStatus: ready
   decisionType: narrowing-and-acceptance-contract
   approver: "@PeterGuy326"
   decidedAt: "2026-09-01T02:54:08Z"

   R2 owner decision — docs-only, Compose-first onboarding

   This comment is the effective product-owner R2 decision. It supersedes earlier proposed R2 wording that was not posted by the product owner. The delivery contract is ready; it is not a PR approval or merge authorization.

   Approved scope

   • README and onboarding documentation lead with the documented Compose path: generate-env → compose up → register → create a folder.
   • Bare-metal remains available only as a development path. Each prerequisite and platform-specific step must state explicit version pins and usable WSL/Linux equivalents alongside the existing macOS guidance.
   • An E3 clean-host run must demonstrate the full four-step closed loop above and record reproducible evidence.

   Boundaries and non-goals

   This is a documentation-only change. It does not authorize changes to runtime behavior, a doctor or first-run CLI surface, Compose topology, Docker behavior, service configuration, or model defaults. The doctor/first-run capability remains exclusively in #112.

   Implementation may now be planned against R2 with normal independent review, required CI, and merge evidence still required.
4. sun-970 commented on Sep 8, 2026

   

   sun-970

   on Sep 8, 2026

   Last edited by sun-970

   Contributor

   More actions

   Review notes

   The R2 narrowing looks sound. A few observations:

   1. REQ-001 scope is well-bounded. The README currently points first-time users at ./scripts/dev_up.sh (line 231) with zero mention of deploy/compose. The fix is a reorder + a pointer to docs/DEPLOYMENT.md, not duplicate prose. Good — duplication would drift.

   2. REQ-002 checklist is concrete and verifiable. The three brew-shaped steps (PostgreSQL+pgvector, MinIO binary, setsid/keg-only resolution in dev_up.sh) are enumerable, so AC-001 can be objectively checked. Suggest formatting the per-platform version pins as a table for easy scanning.

   3. AC-002 evidence bar is appropriate. A clean-host runthrough of the full four-step closed loop (generate-env → compose up → register → folder creation) with reproducible logs is a reasonable acceptance threshold. Consider recording the session as an asciinema cast or timestamped log snippet so future reviewers can verify without re-running the full stack.

   4. Label housekeeping is still pending. The issue still carries type:feature — per the R2 decision it should be type:docs + area:docs. @PeterGuy326, could you update the labels when you get a chance?

   No blockers from my side. The dependency chain (#109 docs → #112 doctor CLI surface) is correctly ordered so P1 delivery is not gated by P2 CLI work.
5. wadrzl commented on Sep 8, 2026

   

   wadrzl

   on Sep 8, 2026

   More actions

   Issue #109 Verification (2026-09-08)

   Baseline: origin/main read today. R2 scope (REQ-003/AC-003 moved to #112). No open PR targets this issue; PRs #126, #148 (docs) and #131 (doctor, retargeted to #112) all closed without merge.

   Requirements (R2 scope)

   Req	Status	Evidence
   REQ-001 (README leads with deploy/compose)	❌ NOT DONE	README.md:231 快速开始 still tells first-time users to run ./scripts/dev_up.sh (bare-metal). deploy/compose is never mentioned in that section; production Compose/Helm appears only as a side note at line 259.
   REQ-002 (Bare-metal demotion + WSL/Linux equivalence)	❌ NOT DONE	docs/RUN_LOCAL.md is entirely brew/macOS-oriented. No platform-equivalence table. The MinIO curl example uses linux-amd64 URLs but is presented as a fallback, not as a peer platform path. scripts/dev_up.sh resolves BREW_PREFIX and dies with brew instructions otherwise.

   Acceptance criteria (R2 scope)

   AC	Status
   AC-001 (README leads with container path; bare-metal demoted + version-pinned WSL/Linux table)	❌ README still bare-metal-first; no platform table exists
   AC-002 (E3 clean-host container runbook: generate-env → compose up → register → folder creation)	❌ No clean-environment evidence attached to any closed or open PR

   Closed PRs — what they attempted and why they did not land

   • docs(onboarding): make deploy/compose the primary onboarding path #126 (docs, closed): first attempt, no detail on closure reason.
   • docs(onboarding): make deploy/compose the primary onboarding path #148 (docs, closed): most complete attempt — README reorder + platform-equivalence table for macOS/Ubuntu-Debian/WSL2. Closed without merge; reason not recorded in the PR body.
   • feat(cli): add mem doctor and first-run guidance that names the documented deploy/compose path #131 (doctor CLI, closed): retargeted to feat(cli): add mem doctor and first-run guidance that names the documented deploy/compose path #112.

   Adjacent state

   • feat(cli): add mem doctor and first-run guidance that names the documented deploy/compose path #112 (mem doctor + first-run guidance): OPEN, owns the REQ-003/AC-003 surface. Correctly depends on docs(onboarding): make deploy/compose the primary onboarding path #109, so P1 docs delivery is not gated.
   • chore(release): sync every version surface to 0.1.2 #168 (version bump to 0.1.2): draft, does not address docs(onboarding): make deploy/compose the primary onboarding path #109.

   Summary

   0/2 requirements met. 0/2 ACs met (R2 scope). Three attempts closed without merge; no open successor. The docs change itself is small (README reorder + one platform table) but has not cleared review. Owner @waterbro-8 is recorded; no label housekeeping done (still type:feature, should be type:docs per R2).
6. waterbro-8 commented on Sep 17, 2026

   

   waterbro-8

   on Sep 17, 2026

   Collaborator

   More actions

   Organization-branch PR: #215.

   README now leads with deploy/compose (generate-env → compose up --wait → register at localhost:8080). Bare-metal dev_up.sh is a development-only subsection. docs/RUN_LOCAL.md adds Ubuntu/Debian and WSL2 equivalents for the brew-only steps.

   AC-003 first-run messaging already names deploy/compose on main via mem doctor (#112). Compose closed-loop on a clean host is NOT VERIFIED in this environment (no Docker daemon). Previous fork #148 remains closed. No merge.
7. PeterGuy326

   added a commit that references this issue on Sep 18, 2026

   docs(onboarding): make deploy/compose the primary onboarding path (#109)

   ...

   884b54d
8. PeterGuy326

   closed this as completedon Sep 18, 2026