Skip to content

Commit f67f888

Browse files
localpiboxlocalpibox
committed
Merge remote-tracking branch 'origin/dev' into HEAD
2 parents 10148ea + 1cdfbe0 commit f67f888

7 files changed

Lines changed: 763 additions & 233 deletions

File tree

‎doc/config-repo.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Config Repo Reference
2+
3+
The **config repo** (`lpb-stack/config`, cloned to `/home/lpb/.pi/agent/`)
4+
is the single source of truth for agent configuration, settings, skills,
5+
and subagent definitions. It is installed into the devstack container at
6+
boot by `start.sh`.
7+
8+
## Directory Structure
9+
10+
```
11+
~/.pi/agent/
12+
├── settings.json.template → template (generated at boot → settings.json)
13+
├── settings.json → runtime config (NOT git-tracked, on host volume)
14+
├── AGENTS.md → agent presets (model config, MCP servers, skills)
15+
├── CONTRIBUTING.md → contribution guidelines
16+
├── VALIDATION.md → validation rules for the stack
17+
├── skills/
18+
│ └── localpibox-repo-workflow/
19+
│ ├── SKILL.md → repository workflow skill
20+
│ └── ...
21+
├── agents/
22+
│ ├── vision-analysis.md → visual analysis subagent
23+
│ ├── browser-automation.md → browser automation subagent
24+
│ ├── exa-search.md → web research subagent
25+
│ ├── researcher.md → researcher subagent
26+
│ ├── README.md → subagent registry
27+
│ └── _template.md → template for new subagents
28+
├── mcp.json → MCP server configuration
29+
├── .env → environment variables (promoted at boot)
30+
├── .env.example → template
31+
└── git/github.com/lpb-stack/
32+
├── lpb-memory/ → memory extension clone
33+
├── pi-subagents/ → subagents extension clone
34+
└── lemonade-pi-plugin/ → lemonade provider extension clone
35+
```
36+
37+
## settings.json Lifecycle
38+
39+
The settings file is **template-driven**, not git-tracked:
40+
41+
1. **Template**: `settings.json.template` ships in the config repo with
42+
`__LPB_VERSION__` placeholders
43+
2. **Boot**: `start.sh` generates `settings.json` by replacing placeholders
44+
3. **No model preconfigured**: user runs `/login lemonade` to set up the provider
45+
4. **Persistence**: `settings.json` lives on the host volume — it survives
46+
container rebuilds
47+
5. **Validation**: `lpb-config validate` checks settings.json pins match
48+
the current stack version
49+
50+
### Example pin format
51+
52+
```json
53+
{
54+
"extensions": {
55+
"@lpb-stack/pi-subagents": {
56+
"git": "github.com/lpb-stack/pi-subagents@0.0.46-lpb-dev"
57+
},
58+
"@lpb-stack/lemonade-pi-plugin": {
59+
"git": "github.com/lpb-stack/lemonade-pi-plugin@0.0.46-lpb-dev"
60+
}
61+
}
62+
}
63+
```
64+
65+
Pins are synced by `lpb-config workspace sync --extensions`.
66+
67+
## Extension Clones
68+
69+
The `git/github.com/lpb-stack/` directory contains runtime clones of the
70+
Pi extensions. They are **not baked into Docker images** — they update at
71+
runtime via `pi update --extensions`.
72+
73+
| Directory | Repo | Role |
74+
|---|---|---|
75+
| `lpb-memory/` | `lpb-stack/lpb-memory` | Persistent memory extension |
76+
| `pi-subagents/` | `lpb-stack/pi-subagents` | Subagent model registry |
77+
| `lemonade-pi-plugin/` | `lpb-stack/lemonade-pi-plugin` | Lemonade provider plugin |
78+
79+
## Runtime State: lpb-memory Dir
80+
81+
The directory `~/.pi/agent/lpb-memory/` holds **runtime state** for the
82+
memory extension — it is NOT in the config repo and NOT git-tracked:
83+
84+
| File | Purpose |
85+
|---|---|
86+
| `USER.md` | User preferences extracted from sessions (by NPU review) |
87+
| `MEMORY.md` | Technical insights extracted from sessions |
88+
| `failures.md` | Lessons learned from mistakes (failure detection) |
89+
90+
This data is created by the lpb-memory extension's subprocess review
91+
system and persists across sessions. It is backed up with the host volume.
92+
93+
## Agents Directory
94+
95+
The `agents/` directory defines **subagent model configurations**. Each
96+
`.md` file specifies:
97+
- The `agent_type` and `model` to use
98+
- The system prompt and tools available
99+
- How the subagent should behave
100+
101+
For example, `vision-analysis.md` defines a subagent that uses the
102+
local Qwen3.6 vision model to analyze browser screenshots.
103+
104+
## Skills Directory
105+
106+
The `skills/` directory contains **reusable procedures** (Pi skills).
107+
Each skill is a directory with `SKILL.md` that defines:
108+
- When to use it
109+
- Step-by-step procedures
110+
- Pitfalls and verification
111+
112+
The only skill shipped with the config repo is:
113+
- `localpibox-repo-workflow` — manage the 6 LocalPibox repos (versioning,
114+
release, workspace sync)
115+
116+
## MCP Configuration
117+
118+
`mcp.json` configures MCP servers available to the agent. It references
119+
servers like `exa`, `agent-browser`, and `context7-mcp` with their
120+
respective connection details and API key sources.
121+
122+
## Quick Reference
123+
124+
```bash
125+
# Check config repo state
126+
lpb-config status
127+
128+
# Update config repo
129+
lpb-config update
130+
131+
# Validate settings.json pins
132+
lpb-config validate
133+
134+
# Sync extension pins to stack version
135+
lpb-config workspace sync --extensions
136+
137+
# Reset config repo
138+
lpb-config reset
139+
```

‎doc/env-vars.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Environment Variables Reference
2+
3+
Environment variables are managed across two layers: **runtime defaults**
4+
(baked into the image), **container `.env`** (user overrides), and **shell
5+
environment** (highest priority).
6+
7+
## Priority Chain (highest → lowest)
8+
9+
1. Shell environment (`export LPB_...`)
10+
2. Devstack `.env` file (at container root, maps `LPB_*` → bare name)
11+
3. Runtime defaults (`lpb.conf.env` baked into image)
12+
4. Hardcoded fallback
13+
14+
## LPB_ Variables
15+
16+
These are the variables read by the `lpb` launcher and `lpb-config`:
17+
18+
| Variable | Default | Purpose |
19+
|---|---|---|
20+
| `LPB_VERSION` | last-used version file | Stack version to run |
21+
| `LPB_TAG` | `dev` | Pipeline selector: `dev` or `main` |
22+
| `LPB_CONTAINER_NAME` | `lpb-stack` | Podman container name |
23+
| `LPB_MODE` | `web` | Image flavour: `cli` or `web` |
24+
| `LPB_RUNTIME` | `podman` | Container runtime: `podman` or `docker` |
25+
| `LPB_MAX_TOKENS_CONTEXT_RATIO` | `0.06` | Max tokens ratio for Qwen reasoning models |
26+
27+
## Bridged Variables (LPB_ → bare name)
28+
29+
`start.sh` at container boot promotes `LPB_*` variables to bare names that
30+
third-party tools expect. This is the **LPB_ bridge**:
31+
32+
| LPB_ Prefix | Bare Name | Used By |
33+
|---|---|---|
34+
| `LPB_EXA_API_KEY` | `EXA_API_KEY` | Exa MCP server |
35+
| `LPB_CONTEXT7_API_KEY` | `CONTEXT7_API_KEY` | Context7 MCP server |
36+
| `LPB_CONNECTION_TOKEN` | `CONNECTION_TOKEN` | OpenVSCode |
37+
| `LPB_EDITOR_HOST` | `HOST` | OpenVSCode |
38+
| `LPB_ED_PORT` | `ED_PORT` | OpenVSCode |
39+
40+
This means setting `LPB_EXA_API_KEY` in the container `.env` file is sufficient —
41+
`start.sh` automatically promotes it to `EXA_API_KEY` the MCP server needs.
42+
43+
## Per-Pipeline Overrides
44+
45+
`lpb.stack.env`, `lpb.stack.dev.env`, and `lpb.stack.main.env` define
46+
pipeline-specific values:
47+
48+
| Variable | dev | main |
49+
|---|---|---|
50+
| `LPB_PI_REF` | `lpb-dev` | `lpb` |
51+
| `LPB_CONFIG_REF` | `dev` | `main` |
52+
53+
The `lpb --tag dev` or `lpb --tag main` flag selects which pipeline profile
54+
to use.
55+
56+
## In-Image Environment
57+
58+
Variables inside the running container (read by Pi and extensions):
59+
60+
| Variable | Purpose |
61+
|---|---|
62+
| `PI_WORKSPACE_ROOT` | Workspace root path |
63+
| `AGENT_DIR` | Config repo directory |
64+
| `LPB_AGENT_GIT` | Extension git clones directory |
65+
| `LEMONADE_BASE_URL` | Model API endpoint (`http://127.0.0.1:13305/v1`) |
66+
| `VISION_MODEL` | Vision model ID (`Qwen3.6-35B-A3B-MTP-GGUF`) |
67+
| `AGENT_BROWSER_SESSION` | Browser session isolation ID |
68+
| `AGENT_BROWSER_ALLOWED_DOMAINS` | Navigation allowlist |
69+
| `AGENT_BROWSER_MAX_OUTPUT` | Max chars for snapshot output (4000) |
70+
71+
## Configuration File Reference
72+
73+
| File | Purpose |
74+
|---|---|
75+
| `.env.example` | Template for container environment variables |
76+
| `.env` | Actual environment (auto-generated on first run) |
77+
| `lpb.conf.env` | Global defaults for the lpb launcher |
78+
| `lpb.stack.env` | Stack-wide variables (shared by dev and main) |
79+
| `lpb.stack.dev.env` | Dev-pipeline overrides |
80+
| `lpb.stack.main.env` | Main-pipeline overrides |
81+
82+
## Quick Reference
83+
84+
```bash
85+
# Override pipeline
86+
export LPB_TAG=main
87+
lpb /project
88+
89+
# Use docker instead of podman
90+
export LPB_RUNTIME=docker
91+
lpb /project
92+
93+
# Check what version is selected
94+
echo $LPB_VERSION
95+
96+
# Pin a specific version
97+
export LPB_VERSION=0.0.54-lpb-dev
98+
lpb /project
99+
```

0 commit comments

Comments
 (0)