Skip to content

Commit f3db8de

Browse files
committed
docs: rewrite documentation for new users — verify every claim against the code
The docs had drifted from reality in ways that actively mislead new users: - README: bare :latest/:cli image tags don't exist (manifest unknown); lpb default mode is the Pi CLI (not VSCodium welcome screen); wrong mount paths (/workspace/... vs /home/lpb/workspace/...); 'pi login' CLI subcommand does not exist (/login is a TUI command); 'update' binary does not exist (pi update --extensions); stale pi upstream baseline (v0.83.0 → v0.84.2); dead lpb-stack/lpb-stack* repo links; CI triggers described as main-only (dev + main) - lpb-cli.md: install claimed sudo + /usr/local/bin (it's ~/.local/bin, no sudo); LPB_MODE/LPB_TAG env vars do not exist in the code; config file names wrong; fake 'lpb run'/'lpb exec' subcommands; self-update described as automatic (it is lpb --update, branch follows the tag); added the real flags (--web/--shell/--ssh, --dev/--main, aliases, pi passthrough) and the real image-resolution rules - env-vars.md: same non-existent vars; .env location fixed (project workspace, optional); real lpb.conf.env defaults; VISION_MODEL does not exist - lpb-config.md: promote description used origin/main+origin/dev for all repos (forks use lpb/lpb-dev); added the 'local stable ahead' case - config-repo.md: pin format was invented (real: packages array with git:owner/repo@tag strings); directory tree corrected against the actual config repo; skills list corrected (3 shipped skills, not 1) - lpb-memory-overview.md: config table did not match the template or extension defaults; llmModelOverride default is the MAIN session model (not qwen3.5-9b-FLM); template ships legacy-inject - lpb-memory-analysis.md: marked as a point-in-time diagnostic - CONTRIBUTING.md: removed dead repo links; feature branches off the default branch (dev/lpb-dev), not the stable branch - new doc/forking.md: extracted the Forking & Repointing guide from the README (README is the docs-site home; kept it lean for new users) - .env.example: stale ~/.localpibox/ paths → ~/.lpb-stack/ - entrypoint comments: bare :cli/:web usage examples → :latest-cli/web - .gitignore: ignore the derived docs/ + site/ build trees
1 parent ceee157 commit f3db8de

13 files changed

Lines changed: 561 additions & 531 deletions

.env.example

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,8 @@ LPB_AGENT_BROWSER_SESSION=${PI_WORKTREE_ID}
4444

4545
# Agent-browser persistent storage on host
4646
# Chrome download, browser profiles, and session state survive container rebuilds.
47-
# Default: ~/.localpibox/agent-browser/
48-
# LPB_AGENT_BROWSER_DIR=$HOME/.localpibox/agent-browser
47+
# Default: ~/.lpb-stack/agent-browser/
48+
# LPB_AGENT_BROWSER_DIR=$HOME/.lpb-stack/agent-browser
4949

5050
# Chrome launch args (container-safe defaults)
5151
LPB_AGENT_BROWSER_ARGS="--no-sandbox,--no-first-run,--disable-gpu,--disable-crashpad"
@@ -82,5 +82,5 @@ LPB_AGENT_BROWSER_IDLE_TIMEOUT_MS=300000
8282
# ─── Persistence ─────────────────────────────────────────────────────────────
8383

8484
# Persist gh CLI auth to ~/.config/gh inside container, stored in
85-
# ~/.localpibox/state/gh-config on the host (in the state volume).
85+
# ~/.lpb-stack/state/gh-config on the host (in the state volume).
8686
# LPB_PERSIST_GH_CONFIG=true

.gitignore

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,8 @@ __pycache__/
77
*.pyo
88
.env
99
node_modules/
10+
11+
# ── Docs site (derived trees — built by scripts/generate.py on the docs
12+
# branch; the tracked content lives in doc/, README.md, ...) ───────────
13+
/docs/
14+
/site/

CONTRIBUTING.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,11 @@ has its own scope:
2222
| [lemonade-pi-plugin](https://github.com/lpb-stack/lemonade-pi-plugin) | Qwen thinking + vision support (fork) |
2323
| [pi-subagents](https://github.com/lpb-stack/pi-subagents) | Centralized subagent model registry (fork) |
2424
| [lpb-memory](https://github.com/lpb-stack/lpb-memory) | Persistent memory / session search extension |
25-
| [lpb-stack](https://github.com/lpb-stack/lpb-stack) | Project overview & stack reference |
26-
| [lpb-stack.github.io](https://github.com/lpb-stack/lpb-stack.github.io) | GitHub Pages project site |
2725

2826
### Process
2927

30-
1. Fork the repo and create a feature branch off its stable branch
31-
(`main` for own repos, `lpb` for forks).
28+
1. Fork the repo and create a feature branch off its default branch
29+
(`dev` for own repos, `lpb-dev` for forks).
3230
2. Make focused changes. **Prefer minimal, targeted patches** over broad
3331
rewrites.
3432
3. For forks, keep work as a **single squashed commit** on `lpb` so the delta

0 commit comments

Comments
 (0)