@phyzess/pappra 0.1.0-beta.1 → 0.1.0-beta.10

package/dist/schemas/install.d.ts

@@ -34,6 +34,13 @@ export declare const runtimeSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     version: z.ZodString;
     path: z.ZodString;
     digest: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"self">;
+    packageName: z.ZodString;
+    version: z.ZodString;
+    packageRoot: z.ZodString;
+    tarball: z.ZodString;
+    digest: z.ZodString;
 }, z.core.$strict>], "kind">;
 export type RuntimeSource = z.infer<typeof runtimeSourceSchema>;
 export declare const runtimeManifestSchema: z.ZodObject<{
@@ -54,6 +61,13 @@ export declare const runtimeManifestSchema: z.ZodObject<{
         version: z.ZodString;
         path: z.ZodString;
         digest: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"self">;
+        packageName: z.ZodString;
+        version: z.ZodString;
+        packageRoot: z.ZodString;
+        tarball: z.ZodString;
+        digest: z.ZodString;
     }, z.core.$strict>], "kind">;
     packageDigest: z.ZodString;
     smoke: z.ZodObject<{

package/dist/schemas/install.js

@@ -43,6 +43,14 @@ export const runtimeSourceSchema = z.discriminatedUnion('kind', [
         path: pathSchema,
         digest: digestSchema,
     }),
+    z.strictObject({
+        kind: z.literal('self'),
+        packageName: z.string().min(1).max(256),
+        version: versionSchema,
+        packageRoot: pathSchema,
+        tarball: pathSchema,
+        digest: digestSchema,
+    }),
 ]);
 export const runtimeManifestSchema = z.strictObject({
     schema: z.literal(RUNTIME_MANIFEST_SCHEMA),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phyzess/pappra",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.10",
   "description": "Portable workspace knowledge and continuity for coding agents.",
   "publishConfig": {
     "access": "public"
@@ -92,6 +92,7 @@
   },
   "devDependencies": {
     "@types/node": "24.19.1",
+    "esbuild": "^0.28.2",
     "prettier": "3.9.9",
     "typescript": "7.0.2"
   },
@@ -103,5 +104,10 @@
     "type": "git",
     "url": "https://github.com/phyzess/pappra.git"
   },
-  "homepage": "https://github.com/phyzess/pappra"
+  "homepage": "https://github.com/phyzess/pappra",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
 }

package/skills/pappra/SKILL.md

@@ -16,13 +16,16 @@ index, or new writer.
 2. Read `references/hosts.md` when the host surface is Pi, Codex, or Claude.
 3. Use `pappra checkpoint` / `pappra resume` for handoffs. A stored checkpoint
    is context, not permission to execute or to trust a previous session.
-4. Use `pappra docs` and `pappra code` only for the workspace selected by the
-   current root. Never infer a workspace from an unrelated session.
+4. Use `pappra docs`, `pappra code`, `pappra runtime` and `pappra host` only for
+   the workspace selected by the current root. Never infer a workspace from an
+   unrelated session. `pappra docs scan --apply` registers discovered documents;
+   `pappra runtime install --apply` keeps a durable copy of this package.
 5. For a new bounded collaboration request, build an explicit
    `pappra/collaboration-goal/1` from the user's objective and named choices,
    run `pappra collab prepare --goal <file> --domain-root <dir>`, admit against a fresh capability
-   card, then use `pappra collab run` with the reviewed controller. Never turn
-   prose into identity, approval, or capability claims.
+   card, then use `pappra collab run` with the reviewed controller. `--controller
+pi-rpc` launches a real owned Pi session and is verified for Pi 1.3.0. Never
+   turn prose into identity, approval, or capability claims.
 
 ## One-request collaboration
 

package/skills/pappra/references/hosts.md

@@ -2,29 +2,39 @@
 
 ## Pi
 
-The integration installs a project extension plus a copied `pappra` skill.
-Pi extensions run with host permissions. Load only a trusted copy from this
-workspace/target; the generated entrypoint imports the fixed Pappra runtime by
-absolute file URL and registers lifecycle handlers only.
+The project integration installs an extension plus a copied `pappra` skill; the
+generated entrypoint imports the fixed Pappra runtime by absolute file URL.
+`pappra host bundle --host pi` exports a self-contained package instead: the
+entry imports `./runtime.mjs` next to it, so the package survives a moved
+checkout. Pi 1.3.0 was verified in a real session through the packaged extension
+(`pi install <dir> -l -a` + `pi -p -a`).
 
 ## Codex
 
-The integration installs a command-hook entry and merges only Pappra-owned
-entries into `hooks.json`. Existing hooks and unrelated keys are preserved.
+Codex 0.163.0 loads command hooks only from its user configuration directory.
+Wire it with `pappra host install --host codex --scope user`, which merges only
+Pappra-owned entries into `$CODEX_HOME/hooks.json` (existing hooks and unrelated
+keys are preserved) and copies the bundled hook there. Project
+`.codex/hooks.json` and plugin-bundle hooks are not loaded at this version.
 Codex hook definitions are trusted individually; installation is not trust.
 Observed 0.163.0 hook keys do not include a compact event, so compact and
 automatic checkpoint requests remain unsupported.
 
 ## Claude Code
 
-The integration installs a command-hook entry and merges only Pappra-owned
-entries into `settings.json`. `SessionStart` and `PostCompact` are distinct;
-matchers, trust, timeout, and output behavior remain host/version-specific.
-Installing a command is not proof it ran.
+The project integration installs a command-hook entry and merges only
+Pappra-owned entries into `settings.json`; the command uses
+`${CLAUDE_PROJECT_DIR}`. `pappra host bundle --host claude --marketplace` exports
+a plugin whose hook uses `${CLAUDE_PLUGIN_ROOT}`; the marketplace validates with
+`claude plugin validate` and startup was verified in a real session. `SessionStart`
+and `PostCompact` are distinct; matchers, trust, timeout, and output behavior
+remain host/version-specific. Installing a command is not proof it ran.
 
 ## Common safety
 
 All surfaces use the event's canonical cwd/root, bounded stdin, a one-second
 local deadline, no transcript reads, no arbitrary configured commands, and no
 network/model/index/session side effects. Paths with spaces or Unicode are
-passed as argv/file URLs, never interpolated into a shell.
+passed as argv/file URLs, never interpolated into a shell. Plugin registration is
+host-specific; never claim a hook is loaded because files were written or a
+validator passed.

package/skills/pappra/references/lifecycle.md

@@ -14,6 +14,10 @@ Pappra distinguishes four local lifecycle intents:
 The matrix is version-specific. A host version outside the observed support
 range is `unsupported`/`unknown`, not a fallback to name similarity.
 
+Codex 0.163.0 loads these hook keys only from its user configuration directory
+(`$CODEX_HOME/hooks.json`); project `.codex/hooks.json` and plugin bundles are
+not loaded by that version. Claude Code and Pi wire hooks in project scope.
+
 ## What a hook does
 
 A hook validates the host payload, resolves the current workspace from the

package/skills/pappra/references/operations.md

@@ -1,13 +1,26 @@
 # Operations reference
 
-- `pappra init` plans or applies workspace configuration.
+- `pappra init` plans or applies workspace configuration. `--yes` derives
+  selections from discovery, `--print-choices` prints that document without
+  writing, `--reconfigure` rebuilds an existing valid `workspace.json`, and
+  `--no-runtime` leaves the durable runtime action pending.
+- `pappra runtime <install|status|verify|remove>` manages the durable runtime
+  copy. `install --apply` defaults to `--from self`; writes require `--apply`.
 - `pappra doctor` is passive: it does not install hooks, start hosts, or fix
-  state.
-- `pappra checkpoint` writes a task checkpoint; `pappra resume` reads a
-  stored snapshot and reports whether execution is allowed.
-- `pappra docs` manages knowledge documents.
-- `pappra code` operates on an explicitly selected repository and keeps
-  index mutations behind an explicit `--apply`.
+  state. `runtime verify` is the active runtime check.
+- `pappra checkpoint` writes a task checkpoint; `pappra resume` reads a stored
+  snapshot and reports whether execution is allowed.
+- `pappra docs <list|check|archive|scan>` manages the knowledge catalog.
+  `scan --apply` registers documents found under the configured sources.
+- `pappra code` operates on an explicitly selected repository and keeps index
+  mutations behind an explicit `--apply`.
+- `pappra host <detect|describe|plan|install|verify|bundle>` wires an optional
+  host. Codex 0.163.0 loads hooks only from `$CODEX_HOME/hooks.json`, so use
+  `install --host codex --scope user`; `bundle --marketplace` exports a plugin
+  directory without registering it, and `install --mode plugin` fails closed.
+- `pappra collab <prepare|run|query>` runs one bounded collaboration request.
+  `run` requires `--controller fixture|pi-rpc`; `pi-rpc` launches a real Pi RPC
+  session.
 
 Preserve user bytes. If an operation reports a conflict or residual path,
 inspect that path and resolve ownership before retrying. Never delete an