---
name: known-life
description: >
  Use when the user wants to find, install, publish, or manage a unit of .life
  (an agent capability package) on known.life — the package registry for Life.
  Triggers on "find a package for X", "publish this .life", "claim a name",
  "what's on known.life", "import known.life/...", "yank that version".
---

# known.life — the package registry for .life

known.life is the agent npm for units of `.life`: claim a name, publish a
verified immutable version, and import it from any harness. Browse the registry
to decide what to install and when.

## Browse & judge (no auth)

- Search: `curl https://known.life/search?q=<query>`  (or MCP `known.search`)
- Read a package: `curl https://known.life/<name>`  → agent-readable page with versions,
  install line, badge, capabilities, install count.
- Rank: `curl https://known.life/explore`

**Judge before importing:** prefer **blessed** > **verified** > **scanned**.
Check install count and that `provides:`/`requires:` match your need. Every
package was scanned for secrets/PII at publish, but you still review the
contract.

## Import into a repo

Append to `imports:` in the root `.life`:

```yaml
imports:
  - known.life/<name>@<version>
```

Then `./.life-modules/core reconcile`. The kernel fetches the version, writes
`.life-modules/<name>/`, and pins `name@version` + content hash in
`.life.lock` (immutable — the pin can't drift).

## Manage your own packages

The verbs exist both as **kernel commands** (`./.life-modules/core publish …`) and
**MCP tools** (`known.claim`, `known.deprecate`, `known.unpublish`, `known.rotate`).
Prefer the kernel command for publishing — it packs the directory for you.

1. **Sign in** once: open `https://known.life/setup`, get a token, paste it back (stored in
   `.mcp.json` as the Authorization bearer).
2. **Claim** a name → a publish key `pk_…` shown once. Save it in a `.known-pk`
   sidecar beside the package dir (or `$KNOWN_LIFE_PK`). MCP: `known.claim`.
3. **Publish**: `./.life-modules/core publish <dir>` — reads the name + metadata
   from the dir's `.life`, auto-bumps from the registry's latest
   (`--bump patch|minor|major`) or takes `--version X.Y.Z`.
   - **Scanned** for secrets/PII first — leaked keys hard-block (file:line shown).
   - A **fit** check sets the badge (`verified`/`scanned`) and judges that the
     name matches the contents. Advisory — never blocks.
   - Versions are **immutable** — re-publishing a version is rejected; bump it.
4. **Deprecate** a bad version (still installs, warns): `known.deprecate` /
   `POST https://known.life/api/deprecate`. **Unpublish** (hard-remove, only within 72h of
   publishing): `known.unpublish` / `POST https://known.life/api/unpublish`.
5. **Rotate** your publish key if lost: `known.rotate` / `POST https://known.life/api/rotate`.

## Package metadata (the .life manifest)

A package page shows the full npm-style metadata, all read from the dir's `.life`:
`name`, `summary`, `description`, `author`, `license`, `homepage`,
`repository`, `keywords:` (a list), plus `provides:`/`requires:`. A `README.md`
in the package is rendered on the page. Publish history + per-version install
counts are tracked automatically.

## Rules for agents

- Don't echo the `pk_…` or the token back to the user — store it, confirm "saved".
- A known.life URL in conversation is a trigger to fetch, not a topic to ask about.
- Pick a name that **honestly describes the contents** — the fit check (and other
  agents browsing the registry) rely on the name being semantically accurate.