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 +39 -33
- package/docs/BEGINNERS.md +22 -0
- package/docs/SETUP.md +83 -40
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
[](https://opensource.org/licenses/MIT)
|
|
6
6
|
[](https://www.typescriptlang.org/)
|
|
7
|
-
[](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
|
-
|
|
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.
|
|
66
|
-
|
|
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
|
-
#
|
|
85
|
+
# 2. Use pi as normal — braid loads automatically
|
|
81
86
|
pi
|
|
82
87
|
```
|
|
83
88
|
|
|
84
|
-
That's it
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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`](
|
|
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`](
|
|
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
|
|
231
|
-
|
|
|
232
|
-
| [`docs/BEGINNERS.md`](docs/BEGINNERS.md)
|
|
233
|
-
| [`docs/SETUP.md`](docs/SETUP.md)
|
|
234
|
-
| [`docs/ROADMAP.md`](docs/ROADMAP.md)
|
|
235
|
-
| [`README.md`](README.md)
|
|
236
|
-
| [`AGENTS.md`](AGENTS.md)
|
|
237
|
-
| [`CONTRIBUTING.md`](CONTRIBUTING.md)
|
|
238
|
-
| [`docs/HISTORY.md`](docs/HISTORY.md)
|
|
239
|
-
| [`../../CHANGELOG.md`](
|
|
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.**
|
|
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
|
|
51
|
+
The minimum, for most users:
|
|
51
52
|
|
|
52
53
|
```bash
|
|
53
|
-
# 1.
|
|
54
|
-
|
|
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.
|
|
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
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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.
|
|
86
|
+
### 1. npm install (recommended)
|
|
87
87
|
|
|
88
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
|
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
|
|
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
|
-
###
|
|
202
|
+
### 6. Direct path from a clone anywhere
|
|
169
203
|
|
|
170
|
-
Same idea as option
|
|
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.
|
|
189
|
-
| 2.
|
|
190
|
-
| 3.
|
|
191
|
-
| 4.
|
|
192
|
-
| 5.
|
|
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
|
|
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`).
|
|
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.
|
|
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",
|