pi-braid 0.40.0 → 0.40.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 CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
6
  [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg)](https://www.typescriptlang.org/)
7
- [![pi-coding-agent ≥ 0.85](https://img.shields.io/badge/pi--coding--agent-%E2%89%A50.85-blueviolet)](https://github.com/earendil-works/pi)
7
+ [![pi-coding-agent ≥ 1.2.0](https://img.shields.io/badge/pi--coding--agent-%E2%89%A51.2.0-blueviolet)](https://github.com/earendil-works/pi)
8
8
 
9
9
  Honest self-aware agent with a metacognitive suite and extras on top of [pi-coding-agent](https://github.com/earendil-works/pi). The suite adds enforcement, memory, reasoning, self-improvement, and structured cognitive signals on top of the pi agent session.
10
10
 
@@ -30,7 +30,21 @@ It runs as a pi _extension package_ - install once, use everywhere on your pi se
30
30
  pi install npm:pi-braid
31
31
  ```
32
32
 
33
- Or point pi at a checked-out workspace in `~/.pi/agent/settings.json`:
33
+ One command, no clone, no build: `pi install` registers the package with pi and
34
+ installs it under pi's npm directory. It carries the suite and the core skill
35
+ set that ships with it. The on-demand skill pack and the other companions are
36
+ add-ons, each its own install: `pi install npm:pi-braid-skills`,
37
+ `pi install npm:pi-braid-contrib`, `pi install npm:pi-braid-providers`,
38
+ `pi install npm:pi-braid-telegram`.
39
+
40
+ ### From a checkout (working on braid)
41
+
42
+ Build the workspace and point pi at the local path:
43
+
44
+ ```bash
45
+ git clone https://github.com/kifirkin/pi-braid.git ~/pi-braid
46
+ cd ~/pi-braid && npm install && npm run build
47
+ ```
34
48
 
35
49
  ```json
36
50
  {
@@ -38,6 +52,9 @@ Or point pi at a checked-out workspace in `~/.pi/agent/settings.json`:
38
52
  }
39
53
  ```
40
54
 
55
+ pi loads each workspace through the `pi.extensions` / `pi.skills`
56
+ fields in its `package.json` (no workspaces auto-discovery - register the paths
57
+ you want).
41
58
  `packages/core` carries the suite and the core skill set that ships with it;
42
59
  `packages/skills` carries the on-demand skill pack, registered per project. Add
43
60
  `packages/providers`, `packages/contrib`, or `packages/telegram` as needed. The install-path
@@ -62,29 +79,18 @@ reference is [`docs/SETUP.md`](docs/SETUP.md).
62
79
  ## Fast start (TL;DR)
63
80
 
64
81
  ```bash
65
- # 1. Clone
66
- git clone https://github.com/kifirkin/pi-braid.git ~/pi-braid
67
- cd ~/pi-braid && npm install && npm run build
68
-
69
- # 2. Register the workspaces you want with pi (one-time, user-global)
70
- # Core is the metacognitive suite and its core skill set; add contrib/providers/telegram as needed.
71
- cat > ~/.pi/agent/settings.json <<'JSON'
72
- {
73
- "packages": [
74
- "file:~/pi-braid/packages/core",
75
- "file:~/pi-braid/packages/contrib"
76
- ]
77
- }
78
- JSON
82
+ # 1. Register braid with pi (one-time, user-global)
83
+ pi install npm:pi-braid
79
84
 
80
- # 3. Use pi as normal — braid loads automatically
85
+ # 2. Use pi as normal — braid loads automatically
81
86
  pi
82
87
  ```
83
88
 
84
- That's it. pi loads each workspace through the `pi.extensions` / `pi.skills`
85
- fields in its `package.json` (no workspaces auto-discovery - register the paths
86
- you want). To enable pi-braid only for one project, or to use all five
87
- workspaces, see [docs/SETUP.md](docs/SETUP.md) § Install paths. For the full setup
89
+ That's it: `pi install` writes the declaration to `~/.pi/agent/settings.json`,
90
+ so there is no clone, no build, and nothing to edit by hand. Working on braid
91
+ itself? [§ Install](#install) carries the checkout path. To enable pi-braid only
92
+ for one project, or to use all five workspaces, see
93
+ [docs/SETUP.md](docs/SETUP.md) § Install paths. For the full setup
88
94
  reference (per-project installs, skills, module toggles, troubleshooting), see
89
95
  **[`docs/SETUP.md`](docs/SETUP.md)**. New to pi and braid? Start with
90
96
  **[`docs/BEGINNERS.md`](docs/BEGINNERS.md)**.
@@ -126,7 +132,7 @@ pi loads extensions from a `packages` entry in `<cwd>/.pi/settings.json` (projec
126
132
  ```
127
133
 
128
134
  This package is the **core** workspace. The monorepo also contains four
129
- sibling packages (see [`../../README.md`](../../README.md) for the full map):
135
+ sibling packages (see [`../../README.md`](https://github.com/kifirkin/pi-braid/blob/main/README.md) for the full map):
130
136
 
131
137
  | Package | Role |
132
138
  | ------------- | -------------------------------------------------------------------- |
@@ -219,7 +225,7 @@ skills in the system prompt's `<available_skills>` block; the agent opens a
219
225
 
220
226
  The catalog table (one row per skill, with its verdict and one-line
221
227
  description, covering both tiers) lives in
222
- **[`../skills/README.md`](../skills/README.md)**, and
228
+ **[`../skills/README.md`](https://github.com/kifirkin/pi-braid/blob/main/packages/skills/README.md)**, and
223
229
  `find packages/core/skills -name SKILL.md | wc -l` counts the core set at any
224
230
  time (`find packages/skills/skills -name SKILL.md | wc -l` counts the pack).
225
231
 
@@ -227,16 +233,16 @@ time (`find packages/skills/skills -name SKILL.md | wc -l` counts the pack).
227
233
 
228
234
  ## Documentation
229
235
 
230
- | Doc | For |
231
- | ------------------------------------------ | ----------------------------------------------------------------------- |
232
- | [`docs/BEGINNERS.md`](docs/BEGINNERS.md) | **First walkthrough**: install → how agents use braid → first extension |
233
- | [`docs/SETUP.md`](docs/SETUP.md) | **Full setup reference**, install paths, troubleshooting |
234
- | [`docs/ROADMAP.md`](docs/ROADMAP.md) | Active roadmap + shipped milestones + open themes |
235
- | [`README.md`](README.md) | This overview |
236
- | [`AGENTS.md`](AGENTS.md) | Repository structure, DOX contract, conventions |
237
- | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Development setup, code style, PR workflow, release |
238
- | [`docs/HISTORY.md`](docs/HISTORY.md) | Consolidated project history, archived roadmap, research |
239
- | [`../../CHANGELOG.md`](../../CHANGELOG.md) | Release notes (curated) |
236
+ | Doc | For |
237
+ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
238
+ | [`docs/BEGINNERS.md`](docs/BEGINNERS.md) | **First walkthrough**: install → how agents use braid → first extension |
239
+ | [`docs/SETUP.md`](docs/SETUP.md) | **Full setup reference**, install paths, troubleshooting |
240
+ | [`docs/ROADMAP.md`](docs/ROADMAP.md) | Active roadmap + shipped milestones + open themes |
241
+ | [`README.md`](README.md) | This overview |
242
+ | [`AGENTS.md`](AGENTS.md) | Repository structure, DOX contract, conventions |
243
+ | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Development setup, code style, PR workflow, release |
244
+ | [`docs/HISTORY.md`](docs/HISTORY.md) | Consolidated project history, archived roadmap, research |
245
+ | [`../../CHANGELOG.md`](https://github.com/kifirkin/pi-braid/blob/main/CHANGELOG.md) | Release notes (curated) |
240
246
 
241
247
  ---
242
248
 
package/docs/BEGINNERS.md CHANGED
@@ -23,6 +23,28 @@ It is a monorepo of five workspaces; the one you care about first is
23
23
 
24
24
  ## 2. Install
25
25
 
26
+ The fast way, from npm:
27
+
28
+ ```bash
29
+ pi install npm:pi-braid
30
+ ```
31
+
32
+ `pi install` registers the package with pi in `~/.pi/agent/settings.json` and
33
+ installs it under pi's npm directory, so there is nothing to clone and nothing
34
+ to build. This one package carries the metacognitive suite and the core skill
35
+ set; the other packages are add-ons:
36
+
37
+ ```bash
38
+ pi install npm:pi-braid-skills # the on-demand skill pack (per project)
39
+ pi install npm:pi-braid-contrib # standalone tool extensions
40
+ pi install npm:pi-braid-providers # extra LLM providers
41
+ pi install npm:pi-braid-telegram # bidirectional Telegram channel
42
+ ```
43
+
44
+ ### Working from a checkout
45
+
46
+ If you want to modify braid or run the latest `main`, clone and build instead:
47
+
26
48
  ```bash
27
49
  git clone https://github.com/kifirkin/pi-braid.git ~/pi-braid
28
50
  cd ~/pi-braid && npm install && npm run build
package/docs/SETUP.md CHANGED
@@ -5,7 +5,7 @@
5
5
 
6
6
  Complete reference for installing braid, configuring pi to load it, enabling companion skill packs, and troubleshooting common setup issues.
7
7
 
8
- > **TL;DR for new users.** Clone → build → register in `~/.pi/agent/settings.json` → done. See the [Fast start](#fast-start) section.
8
+ > **TL;DR for new users.** `pi install npm:pi-braid` → done. See the [Fast start](#fast-start) section.
9
9
 
10
10
  ---
11
11
 
@@ -33,7 +33,8 @@ Complete reference for installing braid, configuring pi to load it, enabling com
33
33
 
34
34
  The Node floor is the `engines` field in `package.json` (mirrored by every
35
35
  workspace manifest); if this table and `engines` ever disagree, trust
36
- `engines`.
36
+ `engines`. git is only needed for the checkout install paths - `pi install`
37
+ from npm needs no checkout at all.
37
38
 
38
39
  **How the pi version resolves.** braid declares the `@earendil-works/pi-*`
39
40
  packages as peer dependencies with unconstrained (`*`) ranges. npm resolves
@@ -47,33 +48,32 @@ version your install resolved to rather than pinning its own;
47
48
 
48
49
  ## Fast start
49
50
 
50
- The three-step minimum:
51
+ The minimum, for most users:
51
52
 
52
53
  ```bash
53
- # 1. Clone and build
54
- git clone https://github.com/kifirkin/pi-braid.git ~/pi-braid
55
- cd ~/pi-braid && npm install && npm run build
54
+ # 1. Install braid from npm (user-global - applies to every pi session)
55
+ pi install npm:pi-braid
56
56
 
57
- # 2. Register with pi (user-global — applies to every pi session)
58
- cat > ~/.pi/agent/settings.json <<'JSON'
59
- {
60
- "packages": [
61
- "file:~/pi-braid/packages/core"
62
- ]
63
- }
64
- JSON
65
-
66
- # 3. Use pi as normal
57
+ # 2. Use pi as normal
67
58
  pi
68
59
  ```
69
60
 
70
61
  That's it. Now every `pi` invocation will load braid alongside pi-core.
62
+ `pi install` writes the declaration to `~/.pi/agent/settings.json` and installs
63
+ the package under pi's npm directory - no clone, no build step. `pi list` shows
64
+ the configured packages.
71
65
 
72
- > **Register `packages/core`, not the repo root.** The root `package.json` has
73
- > no `pi` field, so `file:~/pi-braid` loads nothing. `packages/core` declares
74
- > both `pi.extensions` (the braid extensions) and `pi.skills` (the core skill
75
- > set, which ships inside the package). `packages/skills` carries the on-demand
76
- > set, registered per project - see [§ Skills](#skills).
66
+ Add-ons, each its own install:
67
+
68
+ ```bash
69
+ pi install npm:pi-braid-skills # the on-demand skill pack (per project)
70
+ pi install npm:pi-braid-contrib # standalone tool extensions
71
+ pi install npm:pi-braid-providers # extra LLM providers + the key ring
72
+ pi install npm:pi-braid-telegram # bidirectional Telegram channel
73
+ ```
74
+
75
+ To work on braid itself instead, see [§ Install paths](#install-paths) option 2
76
+ (checkout).
77
77
 
78
78
  ### Verify
79
79
 
@@ -83,9 +83,27 @@ Inside pi, the `<available_skills>` block in the system prompt lists the core sk
83
83
 
84
84
  ## Install paths
85
85
 
86
- ### 1. User-global clone (recommended)
86
+ ### 1. npm install (recommended)
87
87
 
88
- Install once, applies to every pi session across all projects.
88
+ One command, applies to every pi session across all projects:
89
+
90
+ ```bash
91
+ pi install npm:pi-braid
92
+ ```
93
+
94
+ `pi install` writes the package declaration to `~/.pi/agent/settings.json` and
95
+ installs the package under pi's npm directory (`~/.pi/agent/npm/`), so there is
96
+ no clone and no build step. `pi list` shows the configured packages;
97
+ `pi remove npm:pi-braid` removes this one; `pi update --extensions` reconciles
98
+ package installs (see pi's own package docs for the full command set).
99
+
100
+ Add `--local` (or `-l`) to write the declaration to `<project>/.pi/settings.json`
101
+ instead - the natural fit for the per-project [skill pack](#skills).
102
+
103
+ ### 2. User-global checkout (working on braid)
104
+
105
+ For running braid from source - to modify it, or to track `main`. Build the
106
+ checkout, then register the `file:` paths:
89
107
 
90
108
  ```bash
91
109
  git clone https://github.com/kifirkin/pi-braid.git ~/pi-braid
@@ -103,7 +121,13 @@ Settings:
103
121
  }
104
122
  ```
105
123
 
106
- ### 2. Local-packages install (canonical, matches `docs/LOCAL_DEV.md`)
124
+ > **Register `packages/core`, not the repo root.** The root `package.json` has
125
+ > no `pi` field, so `file:~/pi-braid` loads nothing. `packages/core` declares
126
+ > both `pi.extensions` (the braid extensions) and `pi.skills` (the core skill
127
+ > set, which ships inside the package). `packages/skills` carries the on-demand
128
+ > set, registered per project - see [§ Skills](#skills).
129
+
130
+ ### 3. Local-packages install (maintainer)
107
131
 
108
132
  The maintainer path: publish braid into `~/.pi/agent/local-packages`, then
109
133
  register the installed path. `npm run publish:local` packs `packages/core` into
@@ -133,10 +157,19 @@ project that wants it - see [§ Skills](#skills).
133
157
  See [`LOCAL_DEV.md`](LOCAL_DEV.md) for the full publish/link flow, the version
134
158
  scheme, and the skills-collision rule.
135
159
 
136
- ### 3. Project-scoped clone (per-project isolation)
160
+ ### 4. Project-scoped install (per-project isolation)
137
161
 
138
162
  For projects that should always have braid regardless of the user's global config:
139
163
 
164
+ ```bash
165
+ pi install --local npm:pi-braid
166
+ ```
167
+
168
+ `--local` writes the declaration to `<project>/.pi/settings.json`; pi reads
169
+ that file only after project trust is granted.
170
+
171
+ To pin a checkout into the project instead:
172
+
140
173
  ```bash
141
174
  git clone https://github.com/kifirkin/pi-braid.git <project>/.pi/extensions/pi-braid
142
175
  cd <project>/.pi/extensions/pi-braid
@@ -155,19 +188,20 @@ Settings:
155
188
 
156
189
  Project-scoped wins on collision with user-global (per pi's resolution order), and a project-scoped `braid.modules` block is not read by braid at all: pi owns that file and applies it only for a trusted project, so pin braid's module state in `~/.pi/agent/settings.json` or toggle it (which persists under `~/.pi/agent/braid/`).
157
190
 
158
- ### 4. Once-per-session flag (no install)
191
+ ### 5. Once-per-session flag (no install)
159
192
 
160
193
  If you don't want to commit braid to either config - useful for trying it on one task:
161
194
 
162
195
  ```bash
163
- pi -e /path/to/pi-braid/packages/core
196
+ pi -e npm:pi-braid # from npm
197
+ pi -e /path/to/pi-braid/packages/core # from a checkout
164
198
  ```
165
199
 
166
- `pi -e <path>` adds an extension directory for that session only. No clone required; the path must point to a built package (i.e. you've already run `npm install && npm run build`).
200
+ `pi -e <source|path>` adds an extension for that session only. No clone required; a checkout path must point to a built package (i.e. you've already run `npm install && npm run build`).
167
201
 
168
- ### 5. Direct path from a clone anywhere
202
+ ### 6. Direct path from a clone anywhere
169
203
 
170
- Same idea as option 1 but the path can be anywhere on disk:
204
+ Same idea as option 2 but the path can be anywhere on disk:
171
205
 
172
206
  ```bash
173
207
  git clone https://github.com/kifirkin/pi-braid.git /some/other/path
@@ -183,15 +217,16 @@ cd /some/other/path && npm install && npm run build
183
217
 
184
218
  ### Choosing an install path
185
219
 
186
- | Path | Pros | Cons |
187
- | ------------------------- | ---------------------------------------------------------- | --------------------------------------------- |
188
- | 1. User-global clone | One install, all projects | Affects every project (occasionally unwanted) |
189
- | 2. Local-packages install | Versioned tgz or live symlink; matches the maintainer flow | Requires the publish/link step |
190
- | 3. Project-scoped clone | Per-project isolation; version-pinned | Need to rebuild per project after `git pull` |
191
- | 4. `-e` flag | Zero config | Must rebuild each session; easy to forget |
192
- | 5. Direct path | Same as #1 with arbitrary location | Same |
220
+ | Path | Pros | Cons |
221
+ | ------------------------- | ---------------------------------------------------------- | ------------------------------------------- |
222
+ | 1. npm install | One command, no clone or build; all projects | Needs network access for the install |
223
+ | 2. User-global checkout | Run the source; edit and rebuild in place | You own the build; affects every project |
224
+ | 3. Local-packages install | Versioned tgz or live symlink; matches the maintainer flow | Requires the publish/link step |
225
+ | 4. Project-scoped install | Per-project isolation; version-pinned | A checkout needs a rebuild after `git pull` |
226
+ | 5. `-e` flag | Zero config; try one session | Must be passed every time |
227
+ | 6. Direct path | Same as #2 with arbitrary location | Same |
193
228
 
194
- The recommended default is **option 1** for users who want braid everywhere, **option 2** for maintainers following `LOCAL_DEV.md`, **option 3** for users who pin extensions per project.
229
+ The recommended default is **option 1**. Options 2 and 6 are checkout variants for working on braid or tracking `main`; option 3 is the maintainer flow; option 4 isolates one project; option 5 tries it once.
195
230
 
196
231
  ---
197
232
 
@@ -205,7 +240,8 @@ braid's skills come in two tiers.
205
240
  - **On-demand set** - the separate `pi-braid-skills` pack
206
241
  (`packages/skills/skills/`: eight `SKILL.md` plus shared content under
207
242
  `skills/_shared/`), registered in the settings file of the project that wants
208
- it.
243
+ it (`pi install --local npm:pi-braid-skills`, or a `file:` spec from a
244
+ checkout).
209
245
 
210
246
  Every skill is one `SKILL.md`. The catalog table (one row per skill, with its
211
247
  verdict and one-line description, covering both tiers) is
@@ -221,7 +257,14 @@ Skills in a registered package are listed in the system prompt's
221
257
 
222
258
  `pi-braid-skills` and `pi-braid-contrib` are not separate repositories - since
223
259
  the monorepo migration they are in-repo workspaces
224
- (`packages/skills`, `packages/contrib`). Register the workspaces you want:
260
+ (`packages/skills`, `packages/contrib`). From npm:
261
+
262
+ ```bash
263
+ pi install npm:pi-braid-contrib # the code-only extension workspace
264
+ pi install npm:pi-braid-skills # the on-demand skill set, per project
265
+ ```
266
+
267
+ From a checkout, register the workspace paths you want:
225
268
 
226
269
  ```jsonc
227
270
  // ~/.pi/agent/settings.json
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.40.0",
3
+ "version": "0.40.1",
4
4
  "description": "Metacognitive extension suite for pi-coding-agent: enforcement, memory, reasoning, self-improvement, and structured cognitive signals.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",