pico-engine 1.8.0 → 1.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -3
- package/dist/RulesetRegistryLoaderFs.js +46 -4
- package/dist/cli.js +3 -1
- package/dist/engineConfig.js +11 -0
- package/dist/index.js +2 -5
- package/dist/logging.js +148 -4
- package/dist/server.js +206 -1
- package/dist/stageKrl.js +26 -0
- package/dist/xmluiRuntime.js +68 -0
- package/krl/io.picolabs.pico-engine-ui.krl +14 -77
- package/krl/io.picolabs.wrangler.krl +28 -5
- package/krl/io.picolabs.xmlui.krl +305 -0
- package/mcp/devResources.js +17 -7
- package/mcp/docs/CLAUDE.md +85 -0
- package/{public → mcp}/docs/pico-engine.md +15 -11
- package/package.json +11 -7
- package/public/pico-engine-ui.css +1 -1
- package/public/pico-engine-ui.js +27 -25
- package/public/xmlui/0.12.7.js +419 -0
- package/public/xmlui/pico-view-boot.js +153 -0
- package/src/RulesetRegistryLoaderFs.ts +48 -4
- package/src/cli.ts +3 -1
- package/src/engineConfig.ts +18 -0
- package/src/index.ts +4 -6
- package/src/logging.ts +165 -4
- package/src/server.ts +250 -2
- package/src/stageKrl.ts +26 -0
- package/src/xmluiRuntime.ts +66 -0
- package/public/docs/README.md +0 -9
- package/public/docs/_media/logo.png +0 -0
- package/public/docs/_sidebar.md +0 -6
- package/public/docs/contributing.md +0 -64
- package/public/docs/favicon.ico +0 -0
- package/public/docs/index.html +0 -29
- package/public/docs/krl/README.md +0 -3
- package/public/docs/krl/_sidebar.md +0 -10
- package/public/docs/krl/discovery.md +0 -144
- package/public/docs/krl/modules/ctx.md +0 -151
- package/public/docs/krl/modules/event.md +0 -70
- package/public/docs/krl/modules/http.md +0 -42
- package/public/docs/krl/modules/math.md +0 -5
- package/public/docs/krl/modules/schedule.md +0 -5
- package/public/docs/krl/modules.md +0 -11
- package/public/docs/krl/rulesets.md +0 -81
- package/public/docs/krl/stdlib.md +0 -3
- package/public/docs/llms-full.txt +0 -479
- package/public/docs/llms.txt +0 -37
- package/public/docs/openapi.yaml +0 -78
- package/public/docs/pico.md +0 -5
- package/public/docs/rulesets/README.md +0 -25
- package/public/docs/rulesets/io.picolabs.oauth.md +0 -71
- package/public/docs/rulesets/io.picolabs.pds.md +0 -327
- package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +0 -65
- package/public/docs/rulesets/io.picolabs.portable_subtree.md +0 -94
- package/public/docs/rulesets/io.picolabs.subscription.md +0 -398
- package/public/docs/rulesets/io.picolabs.wrangler.md +0 -471
- /package/{public → mcp}/docs/pico-overview.md +0 -0
|
@@ -1,479 +0,0 @@
|
|
|
1
|
-
# Pico Engine — full text bundle
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Pico overview
|
|
7
|
-
|
|
8
|
-
# Picos: what they are, what they enable, and what they are for
|
|
9
|
-
|
|
10
|
-
**Status:** draft (2026-09-24)
|
|
11
|
-
**Audience:** anyone arriving at this repo — contributors, students, integrators — who needs the model in their head before reading the other design docs.
|
|
12
|
-
**Sources:** the design docs in this folder and `MEMORY.md`; the `manifold-api`, `sensor-network`, and `MCPforEXP` repos; the Picolabs wiki; and the picos-tagged posts on windley.com (2013–2026). Links at the end.
|
|
13
|
-
|
|
14
|
-
---
|
|
15
|
-
|
|
16
|
-
## 1. What picos are
|
|
17
|
-
|
|
18
|
-
A **pico** (persistent compute object) is a small, general-purpose, always-online computer that stands in for one entity: a person, a place, a device, an organization, a group, a concept, even a pothole. It has a unique identity, keeps its own state, runs its own programs, and talks to other picos by exchanging events and answering queries. Networks of picos model the world — one addressable actor per thing we care about.
|
|
19
|
-
|
|
20
|
-
Picos are **actors** in the [actor-model](https://en.wikipedia.org/wiki/Actor_model) sense. In response to a message a pico may send messages to other picos, create other picos, and change its internal state, which affects how it handles the next message. Picos share nothing except messages; one pico cannot see or touch another's state.
|
|
21
|
-
|
|
22
|
-
Three kinds of persistence distinguish picos from most other programming models:
|
|
23
|
-
|
|
24
|
-
| Property | Meaning |
|
|
25
|
-
|----------|---------|
|
|
26
|
-
| **Persistent identity** | A pico exists with one stable identity from creation until it is explicitly deleted. Since 1.6 that identity is a portable `did:webvh` that survives moving between engines. |
|
|
27
|
-
| **Persistent state** | A pico's state lives inside it, isolated from every other pico, and is available to any rule that runs there. No external database. |
|
|
28
|
-
| **Persistent availability** | Once created, a pico is always on and ready for events and queries. Restarting the engine changes nothing about what picos exist or know. |
|
|
29
|
-
|
|
30
|
-
### Anatomy of a pico
|
|
31
|
-
|
|
32
|
-
| Part | What it is |
|
|
33
|
-
|------|------------|
|
|
34
|
-
| **Rulesets and event bus** | Behavior is installed as KRL rulesets, loaded by URL and compiled to JavaScript. A rule is event-condition-action: `select when` an event expression matches, evaluate a condition, act, then a postlude that updates state and raises further events. Every incoming event is raised on the pico's internal bus; a salience graph routes it to listening rules, so installing a ruleset subscribes its rules automatically. |
|
|
35
|
-
| **Event-query API** | Not RESTful. The **Sky Event API** delivers events; the **Sky Cloud/Query API** calls shared functions. It is a *meta-API*: a pico's concrete API is whatever its installed rulesets provide, and it can change over the pico's life. |
|
|
36
|
-
| **State: entity variables and PDS** | `ent:` variables are scoped to each ruleset (a closure over its data). The **Pico Data Store** (default since 1.4) is the shared data plane on every pico — profile, namespaced general data, per-ruleset settings — written by `pds` events, read by shared functions. |
|
|
37
|
-
| **Channels (ECIs)** | As many channels as a pico needs, each with an Event Channel Identifier and its own event/query **policy**. Channels are non-correlatable addresses and the local authorization gate. A `discovery` channel on every pico lets integrators learn what it can do. |
|
|
38
|
-
| **Relationships** | Pairwise, bidirectional, policy-gated connections between picos (*subscriptions* before 1.6.2). They form the heterarchical graph applications run on, independent of the parent/child tree and of which engine hosts each pico. |
|
|
39
|
-
| **Parent/child tree + Wrangler** | Every pico except a root has a parent, which installs and initializes it; control of a root implies control of its subtree. **Wrangler**, the pico OS on every pico, exposes lifecycle, channels, and relationships as KRL functions and events. |
|
|
40
|
-
| **Identity** | Three planes: a human unlocks their **root pico** with a passkey (the root is the person's actor on the mesh); picos identify themselves to each other with **DIDs** (`did:webvh` per pico, `did:peer` per relationship, DIDComm across meshes); outside software reaches a mesh with **OAuth** tokens on `/sky/*`. |
|
|
41
|
-
|
|
42
|
-
### Where picos run
|
|
43
|
-
|
|
44
|
-
Picos live in a **pico engine**, an open-source Node.js runtime built on `pico-framework` (lifecycle, channels, LevelDB persistence) and `select-when` (event-expression matching) with a KRL compiler on top. One engine hosts many picos and, since 1.5, many independent **meshes** (a root pico and its descendants) belonging to different owners. Picos on different engines form relationships as easily as picos on the same engine; the engines need no arrangement between them. The engine runs on a Raspberry Pi and on Fargate.
|
|
45
|
-
|
|
46
|
-
The stack above the engine is strictly layered, and the layering is a design rule: engine and wrangler stay domain-agnostic; Manifold and community rulesets supply the vocabulary (owner, thing, community, borrower).
|
|
47
|
-
|
|
48
|
-
```
|
|
49
|
-
engine ← primitives: picos, channels, policy, persistence, DID keys, passkeys, OAuth
|
|
50
|
-
wrangler ← the OS: children, channels, relationships, discovery
|
|
51
|
-
manifold ← a framework for pico meshes: owner, things, communities, registries, notifications
|
|
52
|
-
mesh apps ← sensor-network, SafeAndMine, Fuse-style apps
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
### Lineage
|
|
56
|
-
|
|
57
|
-
Picos grew out of the Kynetx rules engine (2008) and its "personal cloud" era: CloudOS, SquareTag, Fuse (a production connected-car platform, 2013–2015, hundreds of customers and over a thousand devices), and a guard-tour system. The Node rewrite (2017) made the engine small and fast; 1.0 (2021) made it modular; 1.4 added PDS by default; 1.5 (July 2026) brought passkeys and OAuth into the engine; 1.6 (August 2026) shipped DID-based identity and relationships. The motivation has not changed: an Internet of Things that is decentralized, heterarchical, and interoperable — an alternative to the "CompuServe of Things," where people rent connected devices from vendors in the middle.
|
|
58
|
-
|
|
59
|
-
---
|
|
60
|
-
|
|
61
|
-
## 2. What pico features enable
|
|
62
|
-
|
|
63
|
-
The value is the combination: every entity gets a **closure over identity, data, and behavior**.
|
|
64
|
-
|
|
65
|
-
| Feature | What it enables |
|
|
66
|
-
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
67
|
-
| **Persistent identity** (`did:webvh`, channels) | Relationships that outlive restarts and moves; reputation and history; credentials with a durable subject; revocable delegation; a lifecycle that follows the thing across owners. Why SPIFFE was set aside: it names replaceable processes; picos are actors that last. |
|
|
68
|
-
| **Persistent state and availability** (entity vars, PDS) | Databaseless programming; the running system *is* the design, visible live in the developer UI. Data control at the ruleset grain: delete the trip service before transferring a vehicle, keep the maintenance records. Twins keep working while the owner is offline. |
|
|
69
|
-
| **Rules on an event bus** | Each rule is a microservice for one entity. Functionality accretes — install a ruleset and its rules start listening. Correlation ids, scatter-gather, guard rules, scheduled retries, and routed error events make failure-tolerant asynchrony the default. |
|
|
70
|
-
| **Event-query meta-API + discovery** | A pico's API is discoverable at runtime. Home Assistant turns discovery bindings into devices and services; the MCP interface turns them into LLM tools, gated to the rulesets actually installed. |
|
|
71
|
-
| **Channels with policy** | Capability-style security: an ECI is permission to do what its policy allows and nothing more. Separate channels prevent correlation, scope webhooks to one endpoint, and let discovery filter bindings per caller. |
|
|
72
|
-
| **Typed, pairwise relationships** | Heterarchical graphs across the tree and across engines. Rights are *relationships*, not attributes: a fleet can have two owners, a truck can be lent with attenuated rights, a community can accept members from other meshes. The **introduction pattern** — an existing relationship brokers a new one — generalizes to delegation, transfer, and ReBAC. |
|
|
73
|
-
| **Tree + Wrangler** | Programmatic lifecycle: picos create, initialize, and delete picos; prototypes stamp out configured children. Admin rights follow the tree; everything else is conferred by policy. |
|
|
74
|
-
| **Actor concurrency** | Lock-free, isolated, location-transparent. Applications shard naturally — one pico per section, sensor, vehicle — and scale by adding engines. A laptop replayed 44,504 registration events into 8,000+ section picos at 21 events/sec. |
|
|
75
|
-
| **Three-plane identity** | Self-sovereign meshes: no central identity provider, no password database; strangers on different engines trust each other by resolving DIDs, with no federation. Integrators get scoped, revocable OAuth access without becoming the pico. |
|
|
76
|
-
| **Substitutable, small hosting** | A Pi, a community server, or a cloud, with picos movable between them. Compute moves toward the data, and a vendor's cloud shutting down does not brick the thing. |
|
|
77
|
-
|
|
78
|
-
---
|
|
79
|
-
|
|
80
|
-
## 3. Five use cases
|
|
81
|
-
|
|
82
|
-
| Use case | Picos | Relationships | Status |
|
|
83
|
-
|----------|-------|---------------|--------|
|
|
84
|
-
| LoRaWAN sensor network | owner, Manifold hub, sensor communities, sensor things | community ↔ thing; hub ↔ community; Home Assistant via OAuth | Running at the cabin |
|
|
85
|
-
| Connected vehicles, transferable twins | owner, fleet, vehicle | FleetOwner per owner; vehicle ↔ mechanic, insurer, borrower | Fuse shipped 2014; DID-era transfer designed |
|
|
86
|
-
| Personal inventory and lost-and-found | owner, things, communities, tag and skills registries | thing ↔ community; tag → thing via registry | Manifold on 1.5+; tag-scan path in progress |
|
|
87
|
-
| AI that works for the owner | root or household pico and children as memory and event sources | pico ↔ model via webhook or callback; later a local model | Webhook pattern now; `llm:*` designed |
|
|
88
|
-
| High-fan-out institutional systems | institution, index picos, tours, locations, reports; or one pico per course section | personal cloud ↔ institution; collection → members | Guard tour delivered 2014; registration proof 2017 |
|
|
89
|
-
|
|
90
|
-
### 3.1 A LoRaWAN sensor network
|
|
91
|
-
|
|
92
|
-
Battery-powered Dragino sensors in a pump house, a crawl space, a deck, and a beehive report over the Helium network. Each sensor is a **thing pico** in a **sensor community pico** under the owner's Manifold hub. Helium posts each heartbeat to a channel on the sensor's pico; a router ruleset decodes the payload and raises `sensor:new_readings`; a thresholds ruleset raises `sensor:threshold_violation`; the community raises `manifold:add_notification`, and Manifold fans the alert out to whatever the owner enabled (inbox, SMS, Prowl, Home Assistant). Home Assistant connects over OAuth and renders the mesh as devices — history, dashboards, automations — with no custom UI. Picos contribute one actor per sensor with its own decoding, thresholds, and history; communities that own bootstrap and aggregation; a notification platform no domain ruleset reimplements; and a way to admit a machine (the Helium webhook) into an OAuth-locked mesh by exempting one narrow channel. Adding a sensor type is one router ruleset.
|
|
93
|
-
|
|
94
|
-
### 3.2 Connected vehicles and transferable digital twins
|
|
95
|
-
|
|
96
|
-
Fuse gave every vehicle a pico fed by an OBD-II device — trips, fuel, maintenance, diagnostic codes, alerts, each a set of rules in the vehicle pico — with an owner pico and a fleet pico above. Ownership was a **relationship** (`FleetOwner`), so two owners were two relationships, and a new owner was added through the introduction pattern. The design docs carry this forward: a vehicle's relationships with manufacturer, mechanic, insurer, borrower, and DMV are one mechanism with different roles and Rx policies. When Phil sells his truck to Dave on another engine, the truck's `did:webvh` stays the same, parent and community links move to Dave's mesh, and the battery-health service relationship survives via DID rotation. Trip data can be deleted before transfer; maintenance records stay with the vehicle. The twin's identity is bound to the vehicle, not to any owner.
|
|
97
|
-
|
|
98
|
-
### 3.3 Personal inventory, tags, and lost-and-found
|
|
99
|
-
|
|
100
|
-
SquareTag, and now Manifold with SafeAndMine, gives a person a mesh of **thing picos** for the objects they care about — a backpack, a bike, a furnace — grouped into communities. Each thing carries skills: SafeAndMine registers QR/NFC tags in the tag registry and shows owner contact information to a finder who scans one; Journal records notes such as filter changes. Things are created, tagged, and annotated through Home Assistant or through a conversational interface: an MCP server exposes Manifold operations as tools, and skill-gating shows the model only the tools whose rulesets are installed on the pico at hand, offering to install what is missing. Every thing has its own API, skills are installed per thing at runtime, a thing can belong to several communities, and the data stays in the owner's mesh rather than a vendor's account.
|
|
101
|
-
|
|
102
|
-
### 3.4 AI that works for the owner
|
|
103
|
-
|
|
104
|
-
Picos already have what an AI integration needs: persistent identity, owned state, and an event-driven interface. The progression starts shallow — a pico fires an event, an external routine reasons and posts a response event back — then moves to KRL actions that call a model with a callback event, then to the model using pico queries as tools so that the **pico is the memory**, and finally to the model raising events into the pico graph to make things happen. A household pico gives a model a cross-domain view over its children (car, sensors, calendar) while the hierarchy encodes the privacy boundary. The local-model design adds `llm:complete`, `llm:extract`, `llm:classify`, and `llm:summarize` as KRL primitives bounded by channel policy, with the rule that the model *proposes* and KRL *commits*. Fuse's bare alerts are the motivating example: a diagnostic code enriched with context and a recommendation is what drivers needed.
|
|
105
|
-
|
|
106
|
-
### 3.5 High-fan-out institutional systems
|
|
107
|
-
|
|
108
|
-
The **guard tour** system modeled an institution, tours, locations, and reports as separate picos, with index picos mapping identifiers to channels; guards and managers used their own personal clouds with a guard-tour ruleset installed — no accounts in the tour system — plus temporary channels for the duration of a tour. **BYU priority registration** modeled each of 5,393 course sections as a pico keeping its own roster; replaying two days of add/drop requests showed that an actor per entity absorbs a surge without contention. The pattern: many entities with independent state and bursty activity get one pico each, plus collection picos for grouping, and people participate through their own picos rather than an account the institution owns.
|
|
109
|
-
|
|
110
|
-
---
|
|
111
|
-
|
|
112
|
-
## Open work
|
|
113
|
-
|
|
114
|
-
Moving picos between engines ([pico-move.md](./pico-move.md)), pico-level schemas ([pico-schemas.md](./pico-schemas.md)), the `peer` relationship type and ReBAC in community rulesets ([pico-relationships.md](./pico-relationships.md)), delegated admin ([delegated-admin-relationship.md](./delegated-admin-relationship.md)), local LLM primitives ([pico-llm-capabilities.md](./pico-llm-capabilities.md)), and the channel-policy ceiling and pico mirrors (`MEMORY.md` roadmap).
|
|
115
|
-
|
|
116
|
-
## Sources
|
|
117
|
-
|
|
118
|
-
**Actor model:** [Actor model](https://en.wikipedia.org/wiki/Actor_model) — general overview; Hewitt, Bishop and Steiger, *A Universal Modular ACTOR Formalism for Artificial Intelligence* (IJCAI 1973) — the origin; [Agha, *Actors: A Model of Concurrent Computation in Distributed Systems*](https://dspace.mit.edu/handle/1721.1/6952) (MIT AITR-844, 1985) — the canonical treatment.
|
|
119
|
-
|
|
120
|
-
**Repos and docs:** this folder and `MEMORY.md`; [manifold-api](https://github.com/Picolab/manifold-api) (`README.md`, `docs/Manifold.md`, `docs/Managing_PDS.md`); [sensor-network](https://github.com/windley/sensor-network); [MCPforEXP](https://github.com/picolab/MCPforEXP).
|
|
121
|
-
|
|
122
|
-
**Confluence documentation** — the [Pico Labs developer site](https://picolabs.atlassian.net/wiki/spaces/docs/overview) is the reference manual for everything above. Start here: [Pico Engine Quickstart](https://picolabs.atlassian.net/wiki/spaces/docs/pages/19791878) · [Pico Programming Lessons](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1185969). Engine and Wrangler: [Pico Engine](https://picolabs.atlassian.net/wiki/spaces/docs/pages/6356996) · [Wrangler](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1686929547) · [Picos API](https://picolabs.atlassian.net/wiki/spaces/docs/pages/761593879) · [Managing Channels](https://picolabs.atlassian.net/wiki/spaces/docs/pages/11403288) · [Managing Pico Lifecycle](https://picolabs.atlassian.net/wiki/spaces/docs/pages/11403290). KRL: [KRL Manual](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189890) · [Libraries](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189596) · [KRL Cookbook](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1190497). Identity: [Identity System](https://picolabs.atlassian.net/wiki/spaces/docs/pages/3962044419) · [DIDs — Pico Identity](https://picolabs.atlassian.net/wiki/spaces/docs/pages/4033413122) · [Relationships](https://picolabs.atlassian.net/wiki/spaces/docs/pages/4032102406). Platform: [Manifold](https://picolabs.atlassian.net/wiki/spaces/docs/pages/3907190800) · [Pico Data Store](https://picolabs.atlassian.net/wiki/spaces/docs/pages/3907289100).
|
|
123
|
-
|
|
124
|
-
**Blog (windley.com, tag: picos):** [Fundamental Features of Persistent Compute Objects](https://www.windley.com/archives/2013/10/fundamental_features_of_persistent_compute_objects.shtml) · [Pico APIs: Events and Queries](https://www.windley.com/archives/2013/12/pico_apis_events_and_queries.shtml) · [Complex Pico Structures: Guard Tours](https://www.windley.com/archives/2014/01/complex_pico_structures_guard_tours.shtml) · [Fuse as a Microservice Architecture](https://www.windley.com/archives/2014/07/fuse_as_a_microservice_architecture.shtml) · [Fuse with Two Owners](https://www.windley.com/archives/2014/10/fuse_with_two_owners.shtml) · [Reactive Programming with Picos](https://www.windley.com/archives/2015/11/reactive_programming_with_picos.shtml) · [Reactive Programming Patterns: Examples from Fuse](https://www.windley.com/archives/2016/04/reactive_programming_patterns_examples_from_fuse.shtml) · [Using Picos for BYU's Priority Registration](https://www.windley.com/archives/2017/01/using_picos_for_byus_priority_registration.shtml) · [Announcing Pico Engine 1.0](https://www.windley.com/archives/2021/02/announcing_pico_engine_10.shtml) · [Persistence, Programming, and Picos](https://www.windley.com/archives/2021/02/persistence_programming_and_picos.shtml) · [Ten Reasons to Use Picos](https://www.windley.com/archives/2021/07/ten_reasons_to_use_picos_for_your_next_decentralized_programming_project.shtml) · [Alternatives to the CompuServe of Things](https://www.windley.com/archives/2021/07/alternatives_to_the_compuserve_of_things.shtml) · [Monitoring Temperatures in a Remote Pump House](https://www.windley.com/archives/2023/03/monitoring_temperatures_in_a_remote_pump_house_using_lorawan.shtml) · [Building a Conversational Interface for Manifold](https://www.windley.com/archives/2026/04/building_a_conversational_interface_for_manifold_with_mcp_and_picos.shtml) · [AI Integration in Picos Starts with Events](https://www.windley.com/archives/2026/06/ai_integration_in_picos_starts_with_events.shtml) · [Manifold API and Sensor Network](https://www.windley.com/archives/2026/06/manifold_api_and_sensor_network_two_new_repos.shtml) · [Identity for the Pico Engine](https://www.windley.com/archives/2026/07/identity_for_the_pico_engine.shtml) · [Why Not SPIFFE for Pico Identity?](https://www.windley.com/archives/2026/08/why_not_spiffe_for_pico_identity.shtml) · [Moving My Sensor Network onto Manifold](https://www.windley.com/archives/2026/09/moving_my_sensor_network_onto_manifold.shtml).
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
---
|
|
128
|
-
|
|
129
|
-
# Pico engine operator guide
|
|
130
|
-
|
|
131
|
-
# pico-engine — operator guide
|
|
132
|
-
|
|
133
|
-
This document is the **canonical operator reference** for running and configuring the pico engine. It ships with the npm package under `public/docs/` and is indexed in [`llms.txt`](llms.txt).
|
|
134
|
-
|
|
135
|
-
**New to picos?** Read [pico-overview.md](pico-overview.md) — what picos are, why they exist, and the event-query model (`docs/design/pico-overview.md` in the repo).
|
|
136
|
-
|
|
137
|
-
## Documentation source of truth
|
|
138
|
-
|
|
139
|
-
| Location | Role |
|
|
140
|
-
|----------|------|
|
|
141
|
-
| **This file** (`packages/pico-engine/public/docs/`) | Authoritative for install, config, security flags, and deployment. Versioned with the engine; what `npx pico-engine` and agents read. |
|
|
142
|
-
| **README** in the same package | Quick start, CLI overview, OAuth, containers — links here for config details. |
|
|
143
|
-
| **`MEMORY.md`** (engine repo) | Maintainer log: rationale, gotchas, env registry — not end-user docs. |
|
|
144
|
-
| **Confluence / wiki** | Optional mirror for Picolab internal use. **Do not treat Confluence as primary:** edit this file in git first, then update Confluence to match (or replace Confluence pages with a short blurb + link to [GitHub `public/docs/pico-engine.md`](https://github.com/Picolab/pico-engine/blob/main/packages/pico-engine/public/docs/pico-engine.md) on `main` or the release tag). |
|
|
145
|
-
|
|
146
|
-
If Confluence and this guide disagree, **trust the repo at the release you run** (`pico-engine --version`).
|
|
147
|
-
|
|
148
|
-
---
|
|
149
|
-
|
|
150
|
-
## Quick start
|
|
151
|
-
|
|
152
|
-
```sh
|
|
153
|
-
npm install -g pico-engine
|
|
154
|
-
pico-engine
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
Open `http://localhost:3000`. First visit registers a passkey and creates the root pico.
|
|
158
|
-
|
|
159
|
-
Copy the example config and adjust paths:
|
|
160
|
-
|
|
161
|
-
```sh
|
|
162
|
-
mkdir -p ~/.config/pico-engine
|
|
163
|
-
cp "$(npm root -g)/pico-engine/config.example.json ~/.config/pico-engine/config.json
|
|
164
|
-
# or from a git checkout: packages/pico-engine/config.example.json
|
|
165
|
-
pico-engine
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
Show which config file the process will use:
|
|
169
|
-
|
|
170
|
-
```sh
|
|
171
|
-
pico-engine config path
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
Alternate config file (one file **per engine process**):
|
|
175
|
-
|
|
176
|
-
```sh
|
|
177
|
-
pico-engine -c /path/to/engine-a.json
|
|
178
|
-
# or
|
|
179
|
-
PICO_ENGINE_CONFIG=/path/to/engine-a.json pico-engine
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
---
|
|
183
|
-
|
|
184
|
-
## Config file vs data directory
|
|
185
|
-
|
|
186
|
-
| | Config | Data (`home`) |
|
|
187
|
-
|---|--------|----------------|
|
|
188
|
-
| **Default path** | `$XDG_CONFIG_HOME/pico-engine/config.json` or `~/.config/pico-engine/config.json` | `~/.pico-engine/` |
|
|
189
|
-
| **Override** | `PICO_ENGINE_CONFIG`, `pico-engine -c` | config JSON `home`, or `PICO_ENGINE_HOME` |
|
|
190
|
-
| **Contains** | Port, public URL, WebAuthn, security flags, policy ceiling | LevelDB mesh (`db/`), ruleset cache, logs |
|
|
191
|
-
| **Delete to reset** | No — keeps operator settings | Yes — **fresh mesh** (picos, passkeys in DB gone) |
|
|
192
|
-
|
|
193
|
-
**Precedence:** defaults → **environment variables** → **config file** → programmatic overrides (tests). If both env and file set `port`, **the file wins**.
|
|
194
|
-
|
|
195
|
-
In **`NODE_ENV=test`**, the config file is ignored unless `PICO_ENGINE_CONFIG` is set (isolated tests).
|
|
196
|
-
|
|
197
|
-
---
|
|
198
|
-
|
|
199
|
-
## Config JSON fields
|
|
200
|
-
|
|
201
|
-
Example templates: [`config.example.json`](../../config.example.json), [`config.policy-ceiling.example.json`](../../config.policy-ceiling.example.json), [`config.instances.example/`](../../config.instances.example/).
|
|
202
|
-
|
|
203
|
-
| Field | Type | Description |
|
|
204
|
-
|-------|------|-------------|
|
|
205
|
-
| `home` | string | Data directory (supports `~/…`). Default `~/.pico-engine`. |
|
|
206
|
-
| `port` | number | HTTP listen port. Default `3000`. |
|
|
207
|
-
| `baseUrl` | string | Public origin (no trailing slash): WebAuthn, did:webvh, links. Default `http://localhost:3000`. |
|
|
208
|
-
| `allowSelfSignup` | boolean | Open registration after bootstrap. Default `false` (invite-only). |
|
|
209
|
-
| `allowLocalhostChannelBypass` | boolean | Allow `/c/*` from localhost without passkey (dev MCP, KRL HTTP loops). Default `true`. Set `false` in production behind TLS. |
|
|
210
|
-
| `wildcardSkyRequireBearer` | boolean | Require OAuth bearer on `/sky/*` for channels with unrestricted `*.*` allow rules. Default `false` (1.8 opt-in hardening). |
|
|
211
|
-
| `logToStdout` | boolean | Log to stdout instead of a file. Use on Fargate (set `logToStdout: true` in config). |
|
|
212
|
-
| `logFile` | string | Absolute log path when `logToStdout` is false. Values `stdout`, `-`, or `0` force stdout. |
|
|
213
|
-
| `defaultRootPolicyCeiling` | object | Max channel policy for new root picos (`eventPolicy` / `queryPolicy`). See policy example file. |
|
|
214
|
-
| `globalEventDeny` | array | Extra deny rules applied on **every** ECI before channel policy (e.g. block `engine:secret_ping`). |
|
|
215
|
-
| `globalQueryDeny` | array | Same for queries. |
|
|
216
|
-
| `webauthn.rpId` | string | WebAuthn RP ID (usually hostname without port). |
|
|
217
|
-
| `webauthn.origin` | string | Must match browser URL (scheme + host + port). |
|
|
218
|
-
| `webauthn.rpName` | string | Display name in passkey UI. |
|
|
219
|
-
|
|
220
|
-
Legacy top-level `rpID`, `rpName`, `origin` are still accepted if `webauthn` is omitted.
|
|
221
|
-
|
|
222
|
-
---
|
|
223
|
-
|
|
224
|
-
## Environment variables
|
|
225
|
-
|
|
226
|
-
These four env overrides cover config path, data dir, port, and public URL; everything else (WebAuthn, signup, localhost bypass, policy ceiling, logging, …) belongs in the **config file**. Maintainer registry of all env keys: engine repo `MEMORY.md` (Engine environment variables).
|
|
227
|
-
|
|
228
|
-
| Variable | Purpose |
|
|
229
|
-
|----------|---------|
|
|
230
|
-
| `PICO_ENGINE_CONFIG` | Path to config JSON |
|
|
231
|
-
| `PICO_ENGINE_HOME` | Data directory |
|
|
232
|
-
| `PORT` | Listen port (if not in file) |
|
|
233
|
-
| `PICO_ENGINE_BASE_URL` | Public URL |
|
|
234
|
-
|
|
235
|
-
---
|
|
236
|
-
|
|
237
|
-
## Multiple engines on one host
|
|
238
|
-
|
|
239
|
-
Give each process its own config with distinct **`home`**, **`port`**, **`baseUrl`**, and matching **`webauthn.origin`**.
|
|
240
|
-
|
|
241
|
-
```sh
|
|
242
|
-
pico-engine -c ~/.config/pico-engine/engine-a.json # terminal 1
|
|
243
|
-
pico-engine -c ~/.config/pico-engine/engine-b.json # terminal 2
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
Cursor MCP: separate `mcpServers` entries, each with its own `PICO_ENGINE_CONFIG` pointing at the engine you want.
|
|
247
|
-
|
|
248
|
-
Docker: mount **one config file per service** and **one data volume per service** — never share a `home` volume between two running tasks.
|
|
249
|
-
|
|
250
|
-
---
|
|
251
|
-
|
|
252
|
-
## Docker and AWS (summary)
|
|
253
|
-
|
|
254
|
-
Mesh state lives under `home`:
|
|
255
|
-
|
|
256
|
-
| Subdir | Purpose |
|
|
257
|
-
|--------|---------|
|
|
258
|
-
| `db/` | Picos, channels, auth, identity |
|
|
259
|
-
| `rulesets-db/` | Cached ruleset metadata (rebuildable) |
|
|
260
|
-
| `rulesets/` | Compiled ruleset JS |
|
|
261
|
-
|
|
262
|
-
- One writer per data directory (LevelDB).
|
|
263
|
-
- **Fargate:** mount EFS at e.g. `/var/pico-image`, set `home` accordingly, `baseUrl` to public **HTTPS**, `logToStdout: true` in config.
|
|
264
|
-
- Set `allowLocalhostChannelBypass` to **false** on public deployments.
|
|
265
|
-
|
|
266
|
-
Detailed checklists: package **README** § Containers / Fargate.
|
|
267
|
-
|
|
268
|
-
---
|
|
269
|
-
|
|
270
|
-
## Wrangler and bundled rulesets
|
|
271
|
-
|
|
272
|
-
**Wrangler** (`io.picolabs.wrangler`) is the pico **OS** — the **preferred layer** for operating on picos. It wraps engine primitives (persistence, channels, ruleset registry, policy) in stable **`wrangler:*` events and shared queries**: children, channels, ruleset install/flush, relationships, discovery, and schema (`picoSchema`, `rulesetSchema`, `channelSchema`). It is installed on every pico with **PDS**, **subscription**, and **pico-engine-ui**.
|
|
273
|
-
|
|
274
|
-
**Use wrangler, not engine escape hatches.** Application rulesets, integrators, and harnesses should raise **`wrangler` events** and call **`wrangler:*` functions** (or the UI / `/sky/*` / mesh MCP surfaces that send those operations). The engine also exposes lower-level **`ctx:*`** actions and owner-only tooling; those exist for wrangler and the platform rulesets to call, not as the everyday API.
|
|
275
|
-
|
|
276
|
-
If something you need **cannot be done through wrangler**:
|
|
277
|
-
|
|
278
|
-
1. **Red flag — you may be out of bounds.** Lifecycle and mesh structure belong in wrangler (or in a domain framework such as Manifold built *on* wrangler), not in ad hoc `ctx:` calls or custom engine hooks from app KRL.
|
|
279
|
-
2. **Possible bug or missing OS feature.** If the gap is real OS work (a new child type, channel operation, install path, …), [open an issue](https://github.com/Picolab/pico-engine/issues) on **pico-engine** and describe the wrangler-shaped event or query you expected — not a request to bless more direct `ctx` use.
|
|
280
|
-
|
|
281
|
-
**How to interact:** developer UI (Rulesets, Channels, About), **`wrangler:*` on `/sky/event`** where channel policy allows, **`wrangler:picoQuery`** on family channels, and the generated [wrangler API doc](rulesets/io.picolabs.wrangler.md).
|
|
282
|
-
|
|
283
|
-
**Optional** rulesets ship in the same `krl/` directory but are not auto-installed on every pico:
|
|
284
|
-
|
|
285
|
-
| Ruleset | When to install |
|
|
286
|
-
|---------|-----------------|
|
|
287
|
-
| [io.picolabs.oauth](rulesets/io.picolabs.oauth.md) | **Root pico only** — require OAuth bearer on most `/sky/*` traffic (mesh lock) |
|
|
288
|
-
| [io.picolabs.portable_subtree](rulesets/io.picolabs.portable_subtree.md) | Portable subtree export/import (e.g. identity-aware move) |
|
|
289
|
-
|
|
290
|
-
Install optional rulesets from the **Rulesets** tab (URL like `https://your-engine/krl/io.picolabs.oauth.krl`) or send `wrangler:install_ruleset_request`.
|
|
291
|
-
|
|
292
|
-
**Generated API docs** (events, queries, `@example` from KRL annotations) live under **[rulesets/](rulesets/README.md)** — notably [wrangler](rulesets/io.picolabs.wrangler.md). Refresh in a git checkout: `npm run check:krl-schema-samples` then **`npm run generate:llms`** (copies samples into `public/docs/rulesets/`).
|
|
293
|
-
|
|
294
|
-
---
|
|
295
|
-
|
|
296
|
-
## Manifold (mesh framework)
|
|
297
|
-
|
|
298
|
-
Above wrangler sits **[Manifold](https://github.com/Picolab/manifold-api)** — KRL rulesets that define a **personal mesh**: owner, Manifold hub, **things** (devices, vehicles, objects), **communities** (groups of things), tag and skills registries, and centralized notifications. Manifold uses **wrangler** for all lifecycle (`manifold:create_thing` delegates to `wrangler:new_child_request`, and so on); app code should call **`manifold:*` and domain events**, not `ctx:`.
|
|
299
|
-
|
|
300
|
-
Manifold is **not** one product. It is the shared platform for many meshes, for example:
|
|
301
|
-
|
|
302
|
-
- **Fuse-like connected car** networks (owners, vehicles, shared access)
|
|
303
|
-
- **Household / personal IoT** with things and communities
|
|
304
|
-
- **SafeAndMine**, **Home Assistant**, and other integrators shipped from manifold-api
|
|
305
|
-
- **Sensor or industrial monitoring** (separate repos install bootstrap rulesets on the Manifold pico)
|
|
306
|
-
|
|
307
|
-
Install **`io.picolabs.manifold_bootstrap`** on the engine root to stand up the graph; domain repos add their own rulesets on the Manifold child.
|
|
308
|
-
|
|
309
|
-
**Documentation (separate repo):**
|
|
310
|
-
|
|
311
|
-
- Overview: [docs/Manifold.md](https://github.com/Picolab/manifold-api/blob/main/docs/Manifold.md)
|
|
312
|
-
- Agent index: [docs/llms.txt](https://github.com/Picolab/manifold-api/blob/main/docs/llms.txt)
|
|
313
|
-
- Generated ruleset APIs: [docs/rulesets/](https://github.com/Picolab/manifold-api/tree/main/docs/rulesets) (e.g. [manifold_pico](https://github.com/Picolab/manifold-api/blob/main/docs/rulesets/io.picolabs.manifold_pico.md))
|
|
314
|
-
|
|
315
|
-
---
|
|
316
|
-
|
|
317
|
-
## Security and policy (1.8)
|
|
318
|
-
|
|
319
|
-
- **Deny overrides permit** on channel policies (pico-framework 0.8.2+).
|
|
320
|
-
- **Policy ceiling:** parent can cap child channel policies; optional `defaultRootPolicyCeiling` on the root.
|
|
321
|
-
- **Wildcard channels:** opt-in `wildcardSkyRequireBearer` so wide `/sky/*` access requires a validated bearer.
|
|
322
|
-
- **Channel policy audit:** [channel-policy-audit-2026-10.md](https://github.com/Picolab/pico-engine/blob/main/docs/design/channel-policy-audit-2026-10.md) (repo; summary in [1.8.0 release notes](https://github.com/Picolab/pico-engine/blob/main/docs/release/1.8.0.md)).
|
|
323
|
-
|
|
324
|
-
Owner UI uses the **UI channel** (passkey). Automation uses **OAuth** on `/sky/*` and narrow channels — see README § OAuth.
|
|
325
|
-
|
|
326
|
-
---
|
|
327
|
-
|
|
328
|
-
## HTTP surfaces
|
|
329
|
-
|
|
330
|
-
| Path | Auth | Use |
|
|
331
|
-
|------|------|-----|
|
|
332
|
-
| `/` | Browser | Developer UI |
|
|
333
|
-
| `/c/*` | Passkey session (localhost bypass optional) | Developer UI (browser). **Discouraged** for automation and third-party apps — use `/sky/*` or mesh MCP instead. |
|
|
334
|
-
| `/sky/*` | Channel policy ± OAuth bearer | Events, queries, integrators |
|
|
335
|
-
| `/mcp/:eci` | OAuth bearer | Mesh MCP (Streamable HTTP) |
|
|
336
|
-
| `/auth/*` | WebAuthn flows | Registration, login |
|
|
337
|
-
|
|
338
|
-
Local dev MCP: `pico-engine mcp --stdio` — not exposed on hosted load balancers; see [1.8 plan § MCP](https://github.com/Picolab/pico-engine/blob/main/docs/release/1.8.md) (deployment table).
|
|
339
|
-
|
|
340
|
-
---
|
|
341
|
-
|
|
342
|
-
## Agents and KRL authoring
|
|
343
|
-
|
|
344
|
-
- **`krl-check`** on ruleset files before install.
|
|
345
|
-
- **Dev MCP** (stdio): validate, install, flush, raise, query — same mesh as the UI when `PICO_ENGINE_HOME` / config match.
|
|
346
|
-
- **Docs for LLMs:** [`llms.txt`](llms.txt), [`llms-full.txt`](llms-full.txt), [`openapi.yaml`](openapi.yaml). Regenerate after doc edits: `npm run generate:llms` at repo root.
|
|
347
|
-
|
|
348
|
-
---
|
|
349
|
-
|
|
350
|
-
## Troubleshooting
|
|
351
|
-
|
|
352
|
-
| Symptom | Check |
|
|
353
|
-
|---------|--------|
|
|
354
|
-
| Passkey fails | `baseUrl` / `webauthn.origin` match browser URL; HTTPS in production |
|
|
355
|
-
| “Not allowed by channel policy” | Channel event/query policy; ceiling; global deny lists |
|
|
356
|
-
| Install/flush errors in UI | Event-wait returns `events` with `ruleset_install_failed` / `ruleset_flush_failed` and line/col in `errors` |
|
|
357
|
-
| LevelDB LOCK on startup | Unclean shutdown; stop all tasks using the volume; engine may remove stale LOCK |
|
|
358
|
-
| Empty mesh after deploy | Fargate EBS vs EFS — use persistent volume for `home` |
|
|
359
|
-
|
|
360
|
-
Logs: default `$home/pico-engine.log`, or stdout when configured. Engine logs **`txnError`** at error level for ruleset compile failures (includes line/col when available).
|
|
361
|
-
|
|
362
|
-
---
|
|
363
|
-
|
|
364
|
-
## Related docs
|
|
365
|
-
|
|
366
|
-
- [Pico overview / philosophy](pico-overview.md) · [Bundled rulesets (wrangler, PDS, …)](rulesets/README.md) · [Manifold mesh framework](https://github.com/Picolab/manifold-api/blob/main/docs/llms.txt) · [KRL manual](krl/README.md)
|
|
367
|
-
- Package [README](../../README.md) — OAuth, authentication, full container checklist
|
|
368
|
-
- Release [1.8.0 notes](https://github.com/Picolab/pico-engine/blob/main/docs/release/1.8.0.md) — what changed in this line
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
---
|
|
372
|
-
|
|
373
|
-
# Bundled rulesets
|
|
374
|
-
|
|
375
|
-
# Bundled rulesets (generated docs)
|
|
376
|
-
|
|
377
|
-
Markdown here is copied from `tools/krl-schema/samples/` when you run **`npm run generate:llms`** at the repo root. Sources are the annotated KRL under `packages/pico-engine/krl/`. To regenerate samples from KRL: **`npm run check:krl-schema-samples`** (CI) or `node tools/krl-schema/cli.js -f markdown path/to/ruleset.krl`.
|
|
378
|
-
|
|
379
|
-
## OS layer (every pico)
|
|
380
|
-
|
|
381
|
-
Installed on the root pico and on each new child automatically.
|
|
382
|
-
|
|
383
|
-
| Ruleset | Doc |
|
|
384
|
-
|---------|-----|
|
|
385
|
-
| **io.picolabs.wrangler** | [wrangler](io.picolabs.wrangler.md) — **pico OS**; the supported API for mesh lifecycle (not raw `ctx:*`). If an operation is missing here, treat it as out-of-bounds or [file an engine issue](https://github.com/Picolab/pico-engine/issues). |
|
|
386
|
-
| **io.picolabs.pds** | [pds](io.picolabs.pds.md) — profile and shared namespaced data |
|
|
387
|
-
| **io.picolabs.subscription** | [subscription](io.picolabs.subscription.md) — relationships to other picos |
|
|
388
|
-
| **io.picolabs.pico-engine-ui** | [pico-engine-ui](io.picolabs.pico-engine-ui.md) — developer UI channel |
|
|
389
|
-
|
|
390
|
-
## Optional (install when needed)
|
|
391
|
-
|
|
392
|
-
Shipped under `/krl/` on your engine; install from the Rulesets tab or `wrangler:install_ruleset_request` with the ruleset URL.
|
|
393
|
-
|
|
394
|
-
| Ruleset | Doc | Notes |
|
|
395
|
-
|---------|-----|--------|
|
|
396
|
-
| **io.picolabs.oauth** | [oauth](io.picolabs.oauth.md) | **Root pico only** — optional mesh-wide OAuth on `/sky/*` |
|
|
397
|
-
| **io.picolabs.portable_subtree** | [portable_subtree](io.picolabs.portable_subtree.md) | Portable export/import of subtrees (identity-aware move) |
|
|
398
|
-
|
|
399
|
-
Application rulesets (Manifold, your apps) are not bundled; install their KRL URLs like any other ruleset.
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
---
|
|
403
|
-
|
|
404
|
-
# KRL manual
|
|
405
|
-
|
|
406
|
-
# KRL Manual NEXT
|
|
407
|
-
|
|
408
|
-
This is the manual Kinetic Rule Language NEXT
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
---
|
|
412
|
-
|
|
413
|
-
# Contributing
|
|
414
|
-
|
|
415
|
-
# Contributing
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
To run the pico-engine in development mode do the following:
|
|
419
|
-
|
|
420
|
-
```sh
|
|
421
|
-
$ git clone https://github.com/Picolab/pico-engine.git
|
|
422
|
-
$ cd pico-engine
|
|
423
|
-
$ npm run setup
|
|
424
|
-
$ npm start
|
|
425
|
-
```
|
|
426
|
-
|
|
427
|
-
That will start the server and run the test. `npm start` is simply an alias for `cd packages/pico-engine && npm start`
|
|
428
|
-
|
|
429
|
-
**NOTE about dependencies:** generally don't use `npm i`, rather use `npm run setup` from the root. [lerna](https://github.com/lerna/lerna) will link up the packages so when you make changes in one package, it will be used in others.
|
|
430
|
-
|
|
431
|
-
## Improving documentation
|
|
432
|
-
|
|
433
|
-
This documentation site is found in the [docs](https://github.com/Picolab/pico-engine/tree/master/docs) folder at the repository root. The pages are simple markdown files. It uses [docsify](https://docsify.js.org/) to serve it.
|
|
434
|
-
|
|
435
|
-
To preview changes run the docsify local server using `npm run docs`. Then open your browser to the "Listening at" url.
|
|
436
|
-
|
|
437
|
-
## Making changes
|
|
438
|
-
|
|
439
|
-
Use a branch (or fork) to do your work. When you are ready, create a pull request. That way we can review it before merging it into master. (See the git cheatsheet below)
|
|
440
|
-
|
|
441
|
-
### git cheatsheet
|
|
442
|
-
|
|
443
|
-
```sh
|
|
444
|
-
# list your checked out branches
|
|
445
|
-
git branch
|
|
446
|
-
|
|
447
|
-
# list all branches including remote ones you don't have checked out
|
|
448
|
-
git branch -a
|
|
449
|
-
|
|
450
|
-
# checkout a remote branch
|
|
451
|
-
git checkout -t origin/<branch>
|
|
452
|
-
|
|
453
|
-
# switch branches
|
|
454
|
-
git checkout <branch>
|
|
455
|
-
git checkout master
|
|
456
|
-
|
|
457
|
-
# create a new branch off master
|
|
458
|
-
git checkout -b <branch> master
|
|
459
|
-
|
|
460
|
-
# push your local branch to github
|
|
461
|
-
git push -u origin <branch>
|
|
462
|
-
|
|
463
|
-
# to update your branch with the latest in master
|
|
464
|
-
git checkout master
|
|
465
|
-
git pull
|
|
466
|
-
git checkout <branch>
|
|
467
|
-
git merge master
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
# Use github to merge your branch into master using a pull request.
|
|
471
|
-
# On github use the "new pull request" button to make a PR for merging.
|
|
472
|
-
# Once the PR is merged you can delete the branch using the button on github.
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
# Even though the branch is deleted on github, it won't delete it off your local machine.
|
|
476
|
-
# to delete a local branch
|
|
477
|
-
git branch -d <branch>
|
|
478
|
-
```
|
|
479
|
-
|
package/public/docs/llms.txt
DELETED
|
@@ -1,37 +0,0 @@
|
|
|
1
|
-
# Pico Engine docs (llms.txt)
|
|
2
|
-
|
|
3
|
-
Machine-readable index for agents working with picos and KRL.
|
|
4
|
-
|
|
5
|
-
## Start here
|
|
6
|
-
|
|
7
|
-
- Local dev: `npm install -g pico-engine` then `pico-engine` (or repo `npm start`)
|
|
8
|
-
- Agent loop: repo `CLAUDE.md` + `pico-engine mcp --stdio` (see packages/pico-engine/README.md)
|
|
9
|
-
- Validate KRL: `krl-check` / `npm run krl-check`
|
|
10
|
-
|
|
11
|
-
## Docs
|
|
12
|
-
|
|
13
|
-
- Pico overview: pico-overview.md
|
|
14
|
-
- Pico engine operator guide: pico-engine.md
|
|
15
|
-
- Bundled rulesets: rulesets/README.md
|
|
16
|
-
- KRL manual: krl/README.md
|
|
17
|
-
- Contributing: contributing.md
|
|
18
|
-
|
|
19
|
-
## Bundled ruleset API (generated from KRL)
|
|
20
|
-
|
|
21
|
-
- io.picolabs.wrangler: rulesets/io.picolabs.wrangler.md
|
|
22
|
-
- io.picolabs.pds: rulesets/io.picolabs.pds.md
|
|
23
|
-
- io.picolabs.subscription: rulesets/io.picolabs.subscription.md
|
|
24
|
-
- io.picolabs.pico-engine-ui: rulesets/io.picolabs.pico-engine-ui.md
|
|
25
|
-
- io.picolabs.oauth: rulesets/io.picolabs.oauth.md
|
|
26
|
-
- io.picolabs.portable_subtree: rulesets/io.picolabs.portable_subtree.md
|
|
27
|
-
|
|
28
|
-
## Manifold (mesh framework — separate repo)
|
|
29
|
-
|
|
30
|
-
Application layer on wrangler (owner, thing, community). Not shipped inside pico-engine.
|
|
31
|
-
- Index: https://github.com/Picolab/manifold-api/blob/main/docs/llms.txt
|
|
32
|
-
- Generated ruleset APIs: https://github.com/Picolab/manifold-api/tree/main/docs/rulesets
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
## OpenAPI
|
|
36
|
-
|
|
37
|
-
- Sky and channel HTTP: public/docs/openapi.yaml
|
package/public/docs/openapi.yaml
DELETED
|
@@ -1,78 +0,0 @@
|
|
|
1
|
-
openapi: 3.1.0
|
|
2
|
-
info:
|
|
3
|
-
title: Pico Engine HTTP API (subset)
|
|
4
|
-
version: 1.8.0
|
|
5
|
-
description: |
|
|
6
|
-
Subset of the pico-engine surface for integrators and agents.
|
|
7
|
-
Owner UI uses passkey sessions on `/c/*`. External integrators use OAuth bearer on `/sky/*`.
|
|
8
|
-
Mesh MCP uses Streamable HTTP at `/mcp/{eci}` with the same bearer as Sky for that channel.
|
|
9
|
-
servers:
|
|
10
|
-
- url: http://localhost:3000
|
|
11
|
-
description: Local dev
|
|
12
|
-
paths:
|
|
13
|
-
/sky/event/{eci}/{eid}/{domain}/{type}:
|
|
14
|
-
post:
|
|
15
|
-
summary: Send an event (OAuth bearer when required)
|
|
16
|
-
parameters:
|
|
17
|
-
- { name: eci, in: path, required: true, schema: { type: string } }
|
|
18
|
-
- { name: eid, in: path, required: true, schema: { type: string } }
|
|
19
|
-
- { name: domain, in: path, required: true, schema: { type: string } }
|
|
20
|
-
- { name: type, in: path, required: true, schema: { type: string } }
|
|
21
|
-
requestBody:
|
|
22
|
-
content:
|
|
23
|
-
application/json:
|
|
24
|
-
schema: { type: object, additionalProperties: true }
|
|
25
|
-
responses:
|
|
26
|
-
"200":
|
|
27
|
-
description: Event outcome (directives, eid, ruleOutcomes when annotated, events raised in the same transaction)
|
|
28
|
-
/sky/query/{eci}/{rid}/{function}:
|
|
29
|
-
post:
|
|
30
|
-
summary: Run a query (OAuth bearer when required)
|
|
31
|
-
parameters:
|
|
32
|
-
- { name: eci, in: path, required: true, schema: { type: string } }
|
|
33
|
-
- { name: rid, in: path, required: true, schema: { type: string } }
|
|
34
|
-
- { name: function, in: path, required: true, schema: { type: string } }
|
|
35
|
-
requestBody:
|
|
36
|
-
content:
|
|
37
|
-
application/json:
|
|
38
|
-
schema: { type: object, additionalProperties: true }
|
|
39
|
-
responses:
|
|
40
|
-
"200":
|
|
41
|
-
description: Query result JSON
|
|
42
|
-
/c/{eci}/event-wait/{domain}/{name}:
|
|
43
|
-
post:
|
|
44
|
-
summary: Send event and wait for outcome (UI session or localhost)
|
|
45
|
-
parameters:
|
|
46
|
-
- { name: eci, in: path, required: true, schema: { type: string } }
|
|
47
|
-
- { name: domain, in: path, required: true, schema: { type: string } }
|
|
48
|
-
- { name: name, in: path, required: true, schema: { type: string } }
|
|
49
|
-
requestBody:
|
|
50
|
-
content:
|
|
51
|
-
application/json:
|
|
52
|
-
schema: { type: object, additionalProperties: true }
|
|
53
|
-
/c/{eci}/query/{rid}/{name}:
|
|
54
|
-
post:
|
|
55
|
-
summary: Run a query on a channel
|
|
56
|
-
parameters:
|
|
57
|
-
- { name: eci, in: path, required: true, schema: { type: string } }
|
|
58
|
-
- { name: rid, in: path, required: true, schema: { type: string } }
|
|
59
|
-
- { name: name, in: path, required: true, schema: { type: string } }
|
|
60
|
-
requestBody:
|
|
61
|
-
content:
|
|
62
|
-
application/json:
|
|
63
|
-
schema: { type: object, additionalProperties: true }
|
|
64
|
-
/mcp/{eci}:
|
|
65
|
-
get:
|
|
66
|
-
summary: MCP Streamable HTTP (SSE)
|
|
67
|
-
security: [{ bearerAuth: [] }]
|
|
68
|
-
post:
|
|
69
|
-
summary: MCP Streamable HTTP (JSON-RPC)
|
|
70
|
-
security: [{ bearerAuth: [] }]
|
|
71
|
-
/api/dev/local:
|
|
72
|
-
get:
|
|
73
|
-
summary: Localhost-only dev context (root UI ECI)
|
|
74
|
-
components:
|
|
75
|
-
securitySchemes:
|
|
76
|
-
bearerAuth:
|
|
77
|
-
type: http
|
|
78
|
-
scheme: bearer
|
package/public/docs/pico.md
DELETED
|
@@ -1,5 +0,0 @@
|
|
|
1
|
-
# Persistent Compute Objects
|
|
2
|
-
|
|
3
|
-
The philosophy and model doc is **[pico-overview.md](pico-overview.md)** (source: `docs/design/pico-overview.md` in the repo; copied into `public/docs/` by `npm run generate:llms`).
|
|
4
|
-
|
|
5
|
-
Legacy wiki copy: [Persistent Compute Objects on Confluence](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189992) — prefer the repo overview when they differ.
|
|
@@ -1,25 +0,0 @@
|
|
|
1
|
-
# Bundled rulesets (generated docs)
|
|
2
|
-
|
|
3
|
-
Markdown here is copied from `tools/krl-schema/samples/` when you run **`npm run generate:llms`** at the repo root. Sources are the annotated KRL under `packages/pico-engine/krl/`. To regenerate samples from KRL: **`npm run check:krl-schema-samples`** (CI) or `node tools/krl-schema/cli.js -f markdown path/to/ruleset.krl`.
|
|
4
|
-
|
|
5
|
-
## OS layer (every pico)
|
|
6
|
-
|
|
7
|
-
Installed on the root pico and on each new child automatically.
|
|
8
|
-
|
|
9
|
-
| Ruleset | Doc |
|
|
10
|
-
|---------|-----|
|
|
11
|
-
| **io.picolabs.wrangler** | [wrangler](io.picolabs.wrangler.md) — **pico OS**; the supported API for mesh lifecycle (not raw `ctx:*`). If an operation is missing here, treat it as out-of-bounds or [file an engine issue](https://github.com/Picolab/pico-engine/issues). |
|
|
12
|
-
| **io.picolabs.pds** | [pds](io.picolabs.pds.md) — profile and shared namespaced data |
|
|
13
|
-
| **io.picolabs.subscription** | [subscription](io.picolabs.subscription.md) — relationships to other picos |
|
|
14
|
-
| **io.picolabs.pico-engine-ui** | [pico-engine-ui](io.picolabs.pico-engine-ui.md) — developer UI channel |
|
|
15
|
-
|
|
16
|
-
## Optional (install when needed)
|
|
17
|
-
|
|
18
|
-
Shipped under `/krl/` on your engine; install from the Rulesets tab or `wrangler:install_ruleset_request` with the ruleset URL.
|
|
19
|
-
|
|
20
|
-
| Ruleset | Doc | Notes |
|
|
21
|
-
|---------|-----|--------|
|
|
22
|
-
| **io.picolabs.oauth** | [oauth](io.picolabs.oauth.md) | **Root pico only** — optional mesh-wide OAuth on `/sky/*` |
|
|
23
|
-
| **io.picolabs.portable_subtree** | [portable_subtree](io.picolabs.portable_subtree.md) | Portable export/import of subtrees (identity-aware move) |
|
|
24
|
-
|
|
25
|
-
Application rulesets (Manifold, your apps) are not bundled; install their KRL URLs like any other ruleset.
|