Building a Knowledge Pack

A Knowledge Pack is a versioned, signed bundle of engrams. Packs are how PLUR knowledge travels between people, teams, and projects. Background: Knowledge Packs concept.

When to build one

Onboarding — ship every new engineer the team’s conventions.
Open source distribution — publish a pack with your library’s idioms.
Cross-project replay — bundle lessons from one project and replay them in another.
Benchmarking — share a calibrated pack for A/B comparison.

The recipe

1. Curate the engram set

Decide which engrams should travel. Three filters that help:

Scope — plur list --scope project:my-app to start with everything in one project.
Domain — plur list --domain software.deployment for a topical pack.
IDs — explicit --ids ENG-...,ENG-... for hand-picked.

Look through the result and remove what’s personal, ephemeral, or wrong.

2. Export

plur packs export \
  --scope project:my-app \
  --out ./my-deploy-pack \
  --version 1.0.0

What this produces:

my-deploy-pack/
├── manifest.yaml              # name, version, target scope, integrity hash
├── engrams/
│   ├── ENG-PACK-001.yaml
│   ├── ENG-PACK-002.yaml
│   └── ...
└── README.md                  # placeholder — fill it in

The pack manifest looks like:

name:         my-deploy-pack
version:      1.0.0
description:  Deploy conventions for the platform team
author:       you@example.com
license:      Apache-2.0
target_scope: group:acme/platform     # where engrams land on install
engrams:      ./engrams/*.yaml
integrity:    sha256:9c4d...           # auto-computed; verified at install

Edit anything you want before publishing. The integrity hash is recomputed on every packs export.

3. Write the README

Fill in the auto-generated README.md with:

What problem the pack solves.
Who should install it.
The conventions it encodes (high-level — not every engram).
Versioning policy.

A good README is half the value of the pack. Engrams alone don’t tell you why the pack exists.

4. Distribute

Packs are just signed directories. Publish them however you publish artifacts:

Channel	How
GitHub release	Zip the pack directory, attach to a release. Consumers run `plur packs install <release-url>.zip`.
Internal registry	Host on S3, your artifact server, anywhere. Same install URL pattern.
npm scoped package	Publish as `@yourorg/plur-pack-name`. `plur packs install @yourorg/plur-pack-name` resolves via npm.
Direct path	Email the zip, share via Slack. `plur packs install ./my-deploy-pack.zip`.
Git	Commit the pack directory to a repo. `plur packs install git+ssh://...`.

There is no centralised PLUR pack server by default. The community discovery surface at plur packs discover hits a small static index that anyone can submit to.

5. Version

Bump version in manifest.yaml on every change. SemVer:

Patch — typo fixes, rationale improvements.
Minor — new engrams added, no changes to existing.
Major — engrams removed or substantively changed.

Consumers can pin a specific version. Updating happens via uninstall + install of the new version.

Best practices

Keep packs small. 10–50 engrams is a healthy range. Big packs are hard to review and harder to keep coherent.
One pack per topic. Don’t bundle “deploy conventions” with “Python style” — split them.
Mark fragile engrams with contraindications to reduce false-positive injection on the consumer side.
Test installs on a clean PLUR (mv ~/.plur ~/.plur.bak; plur init; plur packs install ./your-pack; plur recall ...) before publishing.

Team packs (Enterprise)

In PLUR Enterprise, packs are first-class:

The admin dashboard can push a pack to every team member’s local PLUR.
Version bumps roll out with audit trail.
Pack export from a group: scope respects the same permission model as direct reads.

The build flow is identical — plur packs export from a developer’s local PLUR — but distribution is server-mediated.

Anti-patterns

Don’t pack personal engrams. user:gregor engrams don’t help anyone else.
Don’t pack stale knowledge. Run plur list --scope X --since 30d to see what’s been used; consider retiring before exporting.
Don’t bypass review for organisation-wide packs. Have someone read every engram you’re about to publish — they’re going to land on real teammates’ machines.