The Day-0 Developer Experience: One Seam for Humans and Agents

In one line: a newcomer — carbon or silicon — goes from nothing to a useful, governed act without reading the kernel’s source; everything else in the developer experience is judged against that bar.

This page is the DX half of the vision. The Trust Machine says why honest data must be the rational choice; Malleable Software says the system must bend without the vendor. This page says what it feels like to build on Vinxi from day 0 — and in what order we make that feeling real.

One persona, not three

The seam is agent-first by decision: fixed verbs × discovered nouns, every read and write through the governed path (The Seam). The consequence is that a human app-builder and an AI agent drive Vinxi through the same surface — discover the nouns, read the schema, act, assert, query. There is no separate “agent API” and “human CLI”; there is one builder-on-the-seam, in two species.

That collapse gives us a free, merciless test harness: the agent is the honest test. A human papers over a broken step with intuition, folklore, or a colleague; an agent cannot. If an agent cannot complete a step through the seam without insider knowledge, that step is a DX bug — for both species at once.

The reframe: from library to operating system

Today Vinxi is a library you embed, dressed as an OS you use. The CLI constructs the kernel in-process; the HTTP surface exposes a fraction of the syscalls; apps render from generated fixtures; “package” means two unrelated things. The discovery seam — type list, explain, find, trace, get, with bad acts rejected before effect — is mature and genuinely good. What is missing is the boundary everything else stands on: a running Vinxi that you are a client of.

Packages that install into a live system, scripts you run against it, apps that render from it, agents that operate it — all of these hang off that one boundary. Building it is therefore not one workstream among many; it is the spine.

The journey

The builder’s day, from first contact:

#	Step	What it feels like
0	Get it	vinxi is an installed binary, not a build step. One binary, two roles: vinxi serve (be a kernel) or point at one (be a client). vinxi up → a live kernel and a client that knows where it is.
1	Meet it	The first move is asking the running system what it is — not reading docs. A fresh kernel already presents its system.* vocabulary through the seam; one call returns the whole capability surface, machine-readable.
2	Install	vinxi install networkaccess is a governed Act against the running kernel’s registry. One package concept provides ontology + surfaces + apps + playbooks. New nouns appear in discovery; new apps appear in the launcher. Idempotent, uninstallable.
3	Use it	act / assert / find / get / trace — every syscall reachable over the wire, local or remote identically, with unknown acts rejected before effect and errors that teach.
4	Extend it	Hitting the edge of the vocabulary is continuous with using it: author an entity type, link, or derivation and install it through the same path as a package — no recompile. The malleability ladder made real at the seam.
5	Script it	Scripting is not a new language; it is the seam, batched and named. vinxi run networkaccess.provision-olt — playbooks discovered from installed packages, named in domain language. Domain verbs live here, never compiled into the kernel.
6	Build on it	The surface you preview is the surface that ships, rendered from the live kernel. The studio authors against real data; the launcher is the shell; path is identity, query is state (Surface Platform).

The one principle that ties the seven together: every layer exposes the same closed loop — discover → act → verify — through one complete seam against one running kernel. The same loop for a value, for vocabulary, for a script, for an app; identical for a human and an agent.

The capability map, in priority order

The full use-case catalog (≈120 cases across 38 themes) and the swarm-executable workstream decomposition live in the day-0 DX design & backlog. This is the distillation — twelve capability areas, five tiers, in build order:

P0 — The spine

1. Client of a running kernel. The installable vinxi; serve/client duality; the complete syscall set over the wire; one config source; vinxi doctor. Everything below depends on it.

P1 — The core journey (make the seven steps real)

2. Onboarding & the self-teaching seam. doctor, tour, describe --json (the agent’s one-call man page), ask grounded in the installed seam, errors that suggest the next command.
3. One package system. The unified manifest (ontology + surfaces + apps + playbooks), install-as-Act into the kernel registry, dependencies, upgrade with preview, scaffolding.
4. Playbooks. vinxi run <package>.<playbook> — discovered, domain-named, reviewable; demonstrate-then-capture; the sanctioned home for domain-language commands.
5. Apps & surfaces over the live kernel. Surface × realm × session × live query → real widgets; the studio authors against the real kernel; the fixture detour dies.

P2 — The OS comes alive

6. The remaining verbs. Subscribe (watch reality change; live surfaces; reactive playbooks), Schedule (the cron of reality; SLA timers; ambient jobs), Call (actuation — drive the device, not just record intent).
7. Agents as first-class operators. Goal → plan → reviewable run with a decision-log preview before commit; capability-scoped grants; specialist agent teams with machine-suspects-human-confirms handoffs; Vinxi as an MCP server; the generated typed SDK.
8. Trust made tactile. why (provenance), log (the git-log of reality), blame, revert (compensating acts), quarantine-a-source; world-health monitors; known-vs-believed made visible; convergence and replay as demonstrable proofs.
9. Spatial-native. Geo queries, map-native surfaces, pathfinding along the network, field navigation. This domain is fiber routes, poles, and polygons — spatial is not optional.

P3 — The customer arrives

10. Reality onboarding & evolution. The ingest wizard (raw data → inferred schema → previewed plan → commit); reconciliation across disagreeing sources; ontology migration with backfill preview; branch/fork/time-travel; changesets reviewed like pull requests.
11. Testing & simulation. vinxi test against an ephemeral kernel; golden surfaces; the live twin projected forward (blast radius, capacity, what-if at scale); synthetic realities for demos and scale tests.

P4 — The platform matures

12. Field, collaboration & platform. Work-order dispatch and field capture (photo → entity, offline queues); the malleability ladder in the hands of non-developers; federation and edge kernels; identity, metering, governance, reporting, channels; the package marketplace.

What this page is not

It is not the execution plan. Phasing, contracts, workstream briefs, and open decisions are deliberately kept in the design & backlog document, which changes as work lands. This page records the destination and the order of march; it should change only when the vision does.