docs(alpha): simplify native setup and verify generic starter creation
This commit is contained in:
+81
-129
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user