docs(alpha): simplify native setup and verify generic starter creation

This commit is contained in:
2026-10-20 21:42:34 +01:00
parent dce2d759d7
commit a40898f79a
10 changed files with 272 additions and 529 deletions
+81 -129
View File
@@ -1,62 +1,82 @@
# First-version tester walkthrough
# Alpha tester walkthrough
Pipelines is a **single-user preview**, like other personal terminal tools—not a
multi-user service. The goal is useful, supervised workflows with inspectable
history. It is not a guarantee that a model completes every task correctly.
Pipelines is a **single-user alpha** for supervised workflows, not a multi-user
service or a guarantee that a model's answer is correct.
## Before installing
## Setup
- Use a Git checkout (including `.git`) so Docker setup can stamp its build identity.
- **Native host installation is the default** (`./install`/`--native`); the
[Docker installation](install.md) is explicit with `./install --docker` and needs
Docker Compose and Python 3. Docker setup builds the Go CLI/TUI clients on the host
only when Go 1.27+ is available.
- Docker setup starts services, asks for ntfy passwords, opens provider sign-in,
and then saves **two separate model defaults** (the interactive harness model and
the new-pipeline model) in two fuzzy pickers. Signing in to a provider is
separate from those saved defaults. Setup makes a small billable
provider-validation call and sends a setup alert. Docker provider sign-in is
separate from your host OpenCode login. Reopen login or the saved defaults later
with `./install --opencode` or `./install --pi`.
- Start with a **disposable repository with no valuable files or secrets**. Stage
tools can read/edit files and execute commands. Permissions and snapshots are not
an OS sandbox; an automatically mounted home directory is not isolation.
- The Pipelines API is unauthenticated. Use your own machine/trusted network only;
do not expose it to the Internet. No multi-user setup is required.
1. Use macOS or Linux with an existing configured harness and the prerequisites
listed in [installation](install.md).
2. From a Git checkout, run `./install`. Native host installation is the default;
Docker is optional with `./install --docker`.
3. Open the web address reported by setup. For terminal use, put the installation's
`bin` directory on PATH and run `pipelines` from your project directory.
4. Setup also starts the authenticated web proxy, server, and ntfy and enables
login startup. See [installation](install.md) for the private web credential
location. The installed CLI's `pipelines service enable` / `service status`
manage that same service; do not start another server manually.
## Install and identify the build
Native setup reuses host harness configuration. Docker has separate persistent
credentials. Never start both installations on the same ports. Do not run the
installer against a shared instance while work is in flight.
From the checkout, run `./install` for the native host installation, or
`./install --docker` for the Docker server + ntfy installation, then restart any
existing TUI. The installer requires a Git checkout; a standalone source archive
cannot self-install.
Follow [installation](install.md) for PATH and provider setup.
Do not start a native server alongside your Docker server.
The browser proxy requires authentication. The underlying Pipelines/harness
control APIs do not: keep them private and never expose them to the Internet.
Use trusted networks and TLS/VPN as appropriate; authentication is not an OS
sandbox for model tools.
Host Go is **optional** and only needed for native host CLI/TUI binaries. Without
host Go you can still run the Docker-contained TUI/CLI against the running server.
Run Compose from the checkout with `--project-directory` (so it finds
`compose.yaml`) and `--workdir "$PWD"` (so the container keeps the actual
disposable workspace):
## First supervised run
```sh
# TUI (allocate a TTY)
docker compose --project-directory /absolute/path/to/pipelines exec --workdir "$PWD" pipelines pipelines
# Plain CLI command (no TTY)
docker compose --project-directory /absolute/path/to/pipelines exec -T --workdir "$PWD" pipelines pipelines <command>
```
1. Pick a disposable project without secrets or valuable uncommitted changes.
A remote browser selects a directory on the **server**, not its own computer.
2. Open **Settings → Templates** in the web app or `:templates` in the TUI.
Create the read-only **review** starter first. Fresh databases have no
published pipelines; choosing a template creates one explicitly.
3. Ask it to review one short file. Watch the graph and inspect the retained
report and the stage's **Audit → Session** evidence.
4. Try a research or document starter. Check citations and quoted source content
yourself; a successful stage is not proof of factual accuracy.
5. Only then try an editing starter. Inspect actual changes and test evidence,
not just the model's summary. Keep version control/backups.
Any host client targets the mapped host port with
`--url ws://127.0.0.1:<actual-mapped-port>/connect`, reading the port from
`docker compose --project-directory /absolute/path/to/pipelines port pipelines 8080`.
The server listens on container port **8080**; only the default host mapping is
**8081**. Prefer the installer-saved configured endpoint when present; never
replace it with a guessed default.
Configuration, provider credentials, drafts, run history and ntfy data live in
Docker volumes and are reused across reinstalls/reconfigures; the visible flow
remains draft → validate → explicit publish → run → inspect. Developer/legacy
native-server instructions stay in the [installation guide](install.md) rather
than competing with first use.
Editing a draft does not publish it. Publication creates an immutable version;
runs retain the version they used. Export/import bundles contain **definitions
only**, not credentials, projects, sessions, drafts, or history.
## Sessions and stopping
Model stages settle their exact native session and verify its export before
handoff. An export failure retains computed output and waits for export-only
recovery. **Retry export only** reads that session again; it does not rerun the
stage. A genuinely missing historical conversation cannot be reconstructed by
inventing messages.
Cancellation/retry is **not rollback**. Earlier file edits or commands remain;
a new execution can repeat side effects. Never delete data/volumes to fix a run.
## Notifications
Browser alerts require the page to be open; closed-app web push is not supported.
ntfy is a separate optional channel and can notify your phone without the
Pipelines Android app. Installation verifies publishing, not reception. Check
your subscription and device reception before relying on it. See [ntfy](ntfy.md).
## Known limits
- Sequential stages within a run; independent workspaces can run concurrently.
- Tools can read/edit files and execute commands. Permissions are not an OS sandbox.
- Diffs, inventories, and session exports have explicit bounds. Partial or missing
evidence must not be interpreted as “nothing changed” or a complete capture.
- Usage budgets depend on provider-reported usage and can overshoot in flight.
Set provider spending limits too.
- Native Windows, every terminal/browser combination, fresh provider OAuth, and
phone dispatch are not established by automated macOS checks. Linux installer
mocks are not a substitute for a real Linux host trial.
## Report a problem
Include OS/architecture, native or Docker install, exact reproduction steps,
expected/actual behavior, and the affected run ID. Capture:
```sh
pipelines version --json
@@ -64,89 +84,21 @@ pipelines ping --json
pipelines status --json
```
`version` identifies the client; `pong.build` identifies the running server.
The full commit is the primary identity. `-dirty` means uncommitted source was
included; two dirty builds at the same commit need not contain the same changes.
Missing `build`, `commit: "unknown"` or `dirty: null` is not an identifiable release.
Capture this information before reporting issues. `--url` and `PIPELINES_URL`
override the saved endpoint; check that you are connected to the intended server.
The client and server can be different builds. Redact tokens, private paths,
prompts, files, diffs, and session content before sharing. Do not post your
database or harness credential/session storage.
## First supervised run
1. Create a disposable repository, then launch `pipelines` **from that directory**.
Docker must see the same absolute path; repositories on another computer are
not uploaded automatically.
2. Use `:templates` and create the **review** starter (read-only, no repository
change). Review its name and publish explicitly. A fresh database is empty;
templates are never auto-published.
3. Open the pipeline and use `:run` with a small task, such as reviewing one short
file in the disposable repository. Review the execution confirmation.
4. Read the retained report and recorded visits. For an editing workflow, inspect
File changes as well as actual file contents and any verification commands.
Model-written claims alone are not verification.
5. Create/edit a draft with `:new` or `:drafts`; validate it, then choose whether to
publish. Editing alone must not change the published definition.
6. Optionally exercise `:export` and `:import`. Identical definitions skip; differing
existing names offer keep existing, keep both, or use imported as a new version.
7. Quit with `:quit`; `q` intentionally does not quit. Reopen to inspect history.
Phone reception is a separate manual check. Install/subscribe in the ntfy app and
confirm receipt before depending on it. The installer confirms publishing, not
delivery to your phone. A review starter does not send alerts automatically.
## Known boundaries
- Sequential stages within a run; no parallel branches. `type=human` decision
stages pause a run for an operator's choice. Independent runs in different
workspaces do execute concurrently.
- Cancellation/retry is **not rollback**. Retry starts from the entry stage with
fresh sessions and the pinned definition; earlier side effects can repeat.
- Diffs are bounded stage-start/stage-end observations, not full backups or proof
of exclusive authorship. Partial/missing captures must not mean “no edits.”
- ZIP bundles transfer definitions only. They do not back up history, drafts,
repositories, OpenCode credentials/sessions or ntfy storage. Preserve persistent
volumes/data; never use `docker compose down -v` as a routine reset/update.
- Token/USD budgets use reported usage and may overshoot in-flight. Prefer provider
account spending limits too; do not interpret these as a guaranteed bill ceiling.
- Live reference evidence is dated and narrow. An existing real run7
(2026-10-11) executed both configured harnesses, OpenCode 2.0.26 and Pi 1.1.0,
with `opencode-go/deepseek-v4.1-flash` stages, and both steps succeeded
(retained captures under `tmp/friend-ui-verification`); a current-source TUI
inspection of that run recorded actual 80x30 and 120x36 renderings. The earlier
[2026-10-10 OpenCode v2.0.20 trial](reference-workflow-results.md) remains the
previous dated evidence. The dated 2026-10-11 final install then completed the
new-source installer and installed-authoring verification: the runtime was
actually installed and used, with run17 executing both real harness stages (see
[installation verification](installation-verification.md)). Other providers, real
outages/long-stream interruption, fresh OAuth and phone delivery are still
pending and are not established by these runs. See
[dated results](reference-workflow-results.md), not just test pass counts.
- Windows-native installation, screen-reader accessibility and every Linux/macOS
terminal combination are not tested. This is not a stability promise for all hosts.
## Report a useful problem
Include client `version --json`, server `ping --json`, OS/architecture, install mode,
the exact command or key sequence, expected/actual behavior, and a minimal sanitized
definition/input. For a run failure include its ID and relevant inspect evidence.
Describe whether it reproduced in a disposable repository. Redact tokens, credentials,
private paths/prompts, file contents and patches before sharing; inspection output
is not automatically safe to post publicly. Do not export your database or OpenCode
credential/session storage as a bug report.
## Maintainer checks without inference or deployment
## Maintainer checks (no live deployment)
```sh
go test -race -count=1 ./...
go test ./...
go vet ./...
node --test web/test/*.test.mjs
python3 -m unittest discover -s scripts -p 'test_*.py'
python3 scripts/smoke-first-install.py
```
The developer-only smoke check builds source binaries and installs the skill into a disposable directory,
starts an isolated loopback server/database, checks build identity, empty initial
state, four starters, draft/validate/publish, identical ZIP import and restart
persistence, then shuts it down and removes only its temporary directory. It does
not call models, send alerts, update your installed clients or deploy Docker services.
It does not replace real-provider, terminal interaction or fresh Docker-install tests.
Live inference remains [explicitly opt-in](reference-workflows.md).
Use isolated prefixes, loopback ports, and scratch databases. The smoke check
does not run models or send alerts. Browser capture instructions are in
[web verification](../web/README.md). Do not restart the operator's services to
test source changes.