Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
a98339b
docs(openspec): draft init/config UX overhaul (3 changes)
Aaronontheweb May 23, 2026
dba0007
docs: address self-scrutiny review of openspec changes
Aaronontheweb May 23, 2026
116aefa
docs(openspec): align init and config workflows
Aaronontheweb May 24, 2026
e402c1e
feat(config): prototype schema-driven search editor
Aaronontheweb May 25, 2026
4f36e07
fix(cli): stabilize init and config TUI flows
Aaronontheweb May 25, 2026
99e0c85
docs(ui): add search config redesign POC
Aaronontheweb May 26, 2026
97e2001
docs(ui): simplify search config mockups
Aaronontheweb May 26, 2026
e7d5345
refine(config): align search editor with init TUI
Aaronontheweb May 26, 2026
6490526
refine(config): introduce typed search editor model
Aaronontheweb May 26, 2026
c98f89a
refine(config): streamline search editor editing
Aaronontheweb May 26, 2026
4856cf7
refine(config): make search setup a focused workflow
Aaronontheweb May 27, 2026
f086d8d
refine(config): keep search save flow in context
Aaronontheweb May 27, 2026
7d13ae8
feat(config): add workflow editor pilot
Aaronontheweb May 28, 2026
58140f9
fix(tui): show active config selections
Aaronontheweb May 28, 2026
b2cbf15
fix(config): preserve inactive exposure settings
Aaronontheweb May 28, 2026
6374476
refine(config): centralize editor session merges
Aaronontheweb May 28, 2026
fbcfb29
fix(config): reset exposure editor on reopen
Aaronontheweb May 28, 2026
a41e353
fix(config): return from search saved screen
Aaronontheweb May 28, 2026
65da27c
refine(config): route search saves through editor session
Aaronontheweb May 28, 2026
47fb381
feat(config): inline enabled feature toggles
Aaronontheweb May 29, 2026
1b6601c
feat(config): add inline security editors
Aaronontheweb May 29, 2026
a3f926d
refine(config): improve audience profile editor
Aaronontheweb May 30, 2026
f84a367
refine(config): use Termina back navigation for MCP grants
Aaronontheweb May 30, 2026
f295d36
refine(config): harden security access editors
Aaronontheweb May 30, 2026
bcaebb5
feat(config): add channels summary page
Aaronontheweb May 30, 2026
cf0b7f4
feat(config): add channels management editor
Aaronontheweb May 31, 2026
eb2f9bc
fix(config): persist channel connection resets
Aaronontheweb May 31, 2026
f37ddca
refine(config): unify channels validation
Aaronontheweb May 31, 2026
90c4bf1
fix(config): validate channel target contracts
Aaronontheweb May 31, 2026
21eea87
chore(opencode): use gpt-5.5 xhigh defaults
Aaronontheweb May 31, 2026
a508a6f
fix(config): restore post-rebase imports
Aaronontheweb May 31, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 31 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ Read first:

- `PROJECT_CONTEXT.md`
- `TOOLING.md`
- `IMPLEMENTATION_PLAN.md`
- `docs/prd/README.md`
- `.opencode/skills/netclaw-*/SKILL.md`
- `.claude/skills/ralph-*.md`
Expand Down Expand Up @@ -88,14 +89,40 @@ task checkboxes in `openspec/changes/*/tasks.md` during RALPH iterations.

Before coding a capability, discover in this order:

1. matching PRD in `docs/prd/`
2. matching engineering spec in `docs/spec/`
3. matching OpenSpec capability in `openspec/specs/`
4. active change plan in `openspec/changes/<name>/`
1. active task in `IMPLEMENTATION_PLAN.md`
2. matching PRD in `docs/prd/`
3. matching engineering spec in `docs/spec/`
4. matching OpenSpec capability in `openspec/specs/`
5. active change plan in `openspec/changes/<name>/`

If planning and implementation artifacts conflict, fix planning artifacts first.
If discovery artifacts conflict with each other, update them before implementing.

## Cross-Boundary Contract Rule

When a change writes data consumed by another subsystem, identify the consumer
before implementation and verify the producer emits the consumer's canonical
representation. This applies to config editors, persistence records, actor
messages, protocol payloads, tool schemas, and security policy inputs.

For configuration changes, tests must prove both:

- invalid or unresolved values are rejected before persistence
- persisted values match what runtime ACL/routing/startup code expects

Do not treat UI-level save success or schema validity as sufficient when runtime
behavior depends on provider IDs, canonical names, permissions, or security
policy keys.

## Automation Floor

Recent regressions define mandatory automated proof classes. TUI text input must
have headless typed-key coverage and native smoke coverage for critical flows.
Dynamic validation must have fake-failure tests proving save is blocked before
persistence. Legacy/new config paradigm changes must have load/round-trip tests
from the old shape to the runtime-consumed shape. Human manual testing is a
last-mile confidence check, not a substitute for these gates.

## Configuration Schema Sync Rule

When adding or changing properties on any `*Config` type in `Netclaw.Configuration`,
Expand Down
32 changes: 32 additions & 0 deletions BACKLOG_PARKING_LOT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Backlog Parking Lot

This file holds non-NOW work so autonomous loops do not accidentally bulldoze
deprioritized tasks. Move items into `IMPLEMENTATION_PLAN.md` only when the user
explicitly changes priority.

## NEXT Candidates

- Webhook service identity and inbound webhook hardening.
- Subagent explicit model selection.
- Subagent parent-context alignment.
- GitHub Copilot provider refinements.
- VLLM capability strategy and timing work.
- Fixed-length approval button labels and richer approval UI.
- Config hot-reload beyond startup-time configuration.
- Operator diagnostics refinements beyond current CLI/doctor/status work.

## LATER Candidates

- Ambient channel monitoring workflows.
- Delegated coding task orchestration.
- Browser automation as a first-class product feature.
- Split gateway/agent process architecture.
- Hosted/multi-tenant operator console.
- Delivery-policy tuning beyond the first Telemetry & Alerting config pass.

## Parking Rule

If a future task is interesting but not necessary for the active milestone, add
it here instead of expanding `NOW`. The implementation plan should stay small
enough that an agent can finish the selected task all the way through runtime
verification.
640 changes: 640 additions & 0 deletions IMPLEMENTATION_PLAN.md

Large diffs are not rendered by default.

132 changes: 91 additions & 41 deletions docs/prd/PRD-004-cli-onboarding-and-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@
commands, Cocona + Termina frameworks)
- Revised: 2026-02-23 (daemon + thin client split, daemon management commands,
offline vs daemon-required command categorization)
- Revised: 2026-05-24 (bootstrap-only `init`, domain-oriented `config`,
init-owned identity re-entry, explicit reset flow)
- Depends on: `PRD-001`, `PRD-002`

## Goal
Expand Down Expand Up @@ -44,42 +46,70 @@ Netclaw ships as two binaries (see PRD-001 for full architecture):
- Configuration files contain API keys/secrets — config read/write commands
operate on local files directly, never query config over the wire

## Two-Phase Onboarding
## Bootstrap and Ongoing Configuration

### Phase 1: CLI Wizard (`netclaw init`)
### Bootstrap: `netclaw init`

Technical setup, no LLM required. `netclaw init` runs as a **lightweight mode**
— no Akka actor system, no persistence, no SignalR. Only config services are
booted. Provider testing uses direct DI service calls (`ChatClientFactory`),
not REST endpoints.
Technical setup, no daemon required. `netclaw init` runs as a lightweight
offline mode: no Akka actor system, no SignalR, no runtime session host.
Provider testing uses direct DI service calls and local validation.

The wizard is **reentrant** — re-running `netclaw init` detects existing config
and shows a section dashboard with status per section. Each section is
independently enterable for modification. First-run guides linearly through
all steps.
`netclaw init` is bootstrap-first and intentionally short.

Steps:
Fresh-install flow:

1. LLM provider configuration (endpoint URL, API key or OAuth device flow,
model selection, connectivity test via direct HTTP to provider)
2. Slack app setup (bot token, app token for Socket Mode)
3. ACL bootstrap (owner identity, initial channel rules)
4. MCP server configuration (optional — Memorizer recommended)
5. Exposure mode selection (local-only default)
6. Health check (verify Slack connection, LLM reachability, MCP connectivity)
model selection, connectivity test)
2. Identity setup (workspaces directory, user name, timezone) with init-owned
regeneration of `SOUL.md` and `TOOLING.md`
3. Security posture (`Personal`, `Team`, `Public`)
4. Enabled Features for `Team` and `Public` only
5. Final validation / health check / next steps

### Phase 2: Conversational Personality Bootstrap (first `netclaw chat`)
Existing-install flow:

Agent-driven setup, requires running LLM:
1. `Redo identity setup`
2. `Open configuration editor`
3. `Start over from scratch`
4. `Cancel`

1. "Hi, I'm Netclaw. Let me learn about you and your setup."
2. Ask about projects to register (repo paths on disk)
3. Discover environment capabilities (scan for installed tools)
4. Write PERSONALITY.md, USER.md, environment inventory
5. Confirm readiness
`Start over from scratch` is owned by the existing-install init menu, not a
hidden flag. It opens a scope selector:

Phase 2 is triggered automatically on first `netclaw chat` if personality files
don't exist. It can also be re-triggered via CLI (`netclaw personality reset`).
1. `Reset setup only`
2. `Full reset`
3. `Cancel`

Both destructive paths require double confirmation.

`Reset setup only` archives and recreates setup-owned state while preserving
working data such as the SQLite database, logs, projects, schedules,
environment, and skills. `Full reset` wipes the entire Netclaw home except the
installed binary payload.

### Ongoing Settings: `netclaw config`

`netclaw config` is the main post-install settings surface. It is a
domain-oriented Termina TUI, not a flat dump of raw config sections.

Top-level domains:

1. `Inference Providers`
2. `Models`
3. `Channels`
4. `Inbound Webhooks`
5. `Skill Sources`
6. `Search`
7. `Browser Automation`
8. `Telemetry & Alerting`
9. `Security & Access`

Command ownership stays explicit:

1. `netclaw init` owns bootstrap and identity re-entry
2. `netclaw config` owns normal post-install tuning
3. `netclaw provider` and `netclaw model` remain their canonical standalone
entrypoints and may be routed to from `netclaw config`

## Command Surface (MVP)

Expand All @@ -101,12 +131,16 @@ don't exist. It can also be re-triggered via CLI (`netclaw personality reset`).

### TUI-Interactive Commands (Termina, offline)

- `netclaw init` — guided first-time setup wizard (7-step TUI wizard). Reads
and writes local config files directly. No daemon required.
- `netclaw init` — guided bootstrap wizard plus rare existing-install
identity/reset re-entry. Reads and writes local config files directly. No
daemon required.
- `netclaw config` — domain-oriented post-install settings dashboard. Reads and
writes local config files directly. No daemon required.
- `netclaw provider` — bare invocation launches interactive provider manager.
- `netclaw model` — bare invocation launches interactive model manager.

### Onboarding and Configuration (Plain CLI, offline)

- `netclaw config show|validate` — display/validate current configuration
- `netclaw personality reset` — re-trigger conversational personality setup
- `netclaw project list|add|remove` — project registry management (local files)
- `netclaw environment scan|show` — capability self-discovery (scans local system)
Expand Down Expand Up @@ -155,11 +189,22 @@ Onboarding captures all Phase 1 setup items in a stepwise flow.
`netclaw init` SHALL support an interactive guided onboarding flow that:

1. Captures LLM provider configuration (OpenRouter default, OAuth or API key)
2. Configures Slack Socket Mode credentials (bot token + app token)
3. Scaffolds ACL in default-deny mode with owner identity
4. Optionally configures MCP servers (Memorizer recommended)
5. Selects exposure mode (local default)
6. Runs final validation and prints next-step run commands
2. Captures init-owned identity settings and regenerates `SOUL.md` /
`TOOLING.md`
3. Selects security posture (`Personal`, `Team`, `Public`)
4. Continues into Enabled Features when posture is `Team` or `Public`
5. Runs final validation and prints next-step run commands

### CLI-001B Post-Install Configuration

`netclaw config` SHALL be the primary post-install settings surface. It SHALL:

1. Launch a domain-oriented dashboard
2. Route providers/models to their dedicated interactive managers
3. Group `Security Posture`, `Enabled Features`, `Audience Profiles`, and
`Exposure Mode` under `Security & Access`
4. Refuse with a plain non-zero message directing the operator to
`netclaw init` when no install exists

### CLI-002 Validation

Expand Down Expand Up @@ -192,10 +237,12 @@ and active tool grants for the session.
Commands default to read-only behavior unless explicit write/apply flags are
provided.

### CLI-007 Onboarding Resume
### CLI-007 Existing-Install Re-entry

The onboarding flow SHALL be resumable and indicate which setup steps are
completed, pending, or invalid.
When `netclaw init` runs on an existing install, it SHALL present an explicit
action menu rather than silently re-entering the full bootstrap flow. Identity
re-entry remains init-owned; all normal configuration edits route to
`netclaw config`.

### CLI-008 Project Registration

Expand All @@ -218,9 +265,11 @@ Results are persisted to the environment inventory file.

### CLI-010 TUI Commands

`netclaw init` and `netclaw chat` SHALL use Termina 0.5.1 for interactive TUI
rendering. All other commands SHALL use plain console output. TUI commands SHALL
launch Termina as a hosted service within the mode-selected host builder.
`netclaw init`, `netclaw config`, and `netclaw chat` SHALL use Termina 0.5.1
for interactive TUI rendering. Bare `netclaw provider` and `netclaw model`
SHALL also use Termina. All other commands SHALL use plain console output. TUI
commands SHALL launch Termina as a hosted service within the mode-selected host
builder.

### CLI-011 Chat Thin Client

Expand Down Expand Up @@ -267,7 +316,8 @@ endpoints. No TUI rendering. This is the primary production entry point.
2. Every high-risk command has confirmation or explicit `--yes` semantics.
3. Error output includes remediation guidance.
4. Fresh install reaches a runnable baseline in one guided flow.
5. Personality bootstrap triggers automatically on first conversation.
5. Existing installs can re-enter identity setup or open `netclaw config`
without replaying full bootstrap.
6. Environment scan discovers and persists capability inventory.
7. Project registration persists project registry to disk.

Expand Down
Loading
Loading