@phyzess/pappra 0.1.0-beta.2 → 0.1.0-beta.4

package/README.md

@@ -27,14 +27,31 @@ npx @phyzess/pappra@beta doctor --json
 
 `examples/minimal-choices.json` is complete for a host-free, no-graph, single-directory workspace. The example intentionally has no repositories or optional hosts.
 
-`init --json` without `--config` fails closed because JSON mode does not open the interactive wizard; run `npx @phyzess/pappra@beta init` without `--json` in a TTY if you want to enter selections interactively. `--config` and `--json` never prompt.
+For a non-interactive derived setup, `npx @phyzess/pappra@beta init --yes --apply --json` derives repositories, knowledge sources, code engine, validation commands, excludes and hosts from discovery. `--print-choices` prints that `pappra/init-choices/1` document and writes nothing, and `init --json` without selections returns the discovery candidates plus the suggested document. JSON mode never prompts; only a TTY without selections opens the wizard.
 
 Development from a checkout works the same way: `pnpm install --frozen-lockfile`, `pnpm build`, then invoke `dist/cli/main.js` by absolute path from the target workspace.
 
-An apply result can be `ok:true` with `status:"external-actions-pending"` and a
-nonzero process exit. That is a successful, partial configuration write, not a
-claim that a runtime or external tool was installed. Inspect `pendingExternalActions`
-and run `doctor` before adding optional integrations.
+`init --apply` also installs a durable runtime copy of the executing package under the
+Pappra data directory and binds it in `machine.json`, so an npx/dlx bootstrap survives
+cache eviction and the command converges with exit code `0`. Pass `--no-runtime` to leave
+that action pending instead; the result is then `ok:true` with
+`status:"external-actions-pending"` and a nonzero exit, which is a partial configuration
+write rather than a claim that a runtime exists.
+
+The runtime copy can be managed directly:
+
+```sh
+npx @phyzess/pappra@beta runtime install --apply [--from self|tarball|registry]
+npx @phyzess/pappra@beta runtime status --json
+npx @phyzess/pappra@beta runtime verify --json
+```
+
+A workspace that already has a valid `.pappra/workspace.json` is never rewritten silently.
+`init --yes --reconfigure --apply` rebuilds it from discovery (for example to move the
+recorded runtime version to the running package), backing the previous file up under
+`.pappra/local/backups`. Apply also reports advisory `nextActions`: `pappra code prepare`
+for a selected code engine and `pappra docs scan --apply` to register documents from the
+configured knowledge sources.
 
 Optional examples have prerequisites rather than generated files: code-graph and
 host commands require the selected external CLI/support, and collaboration
@@ -46,7 +63,7 @@ requires an explicit controller. They are not needed for the core workflow above
 - **Knowledge:** workspace and private document catalogs with explicit preview/apply operations.
 - **Continuity:** private task checkpoints and bounded advisory resume packets. Resume never grants execution by itself.
 - **Code intelligence:** status, explicit preparation and bounded query for selected repositories. Text/structure fallback is available when the optional graph engine is absent.
-- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration.
+- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration. Hooks are copied as a dependency-free bundle into the host root; `host bundle` exports a native plugin/package directory without registering it. `host install --mode plugin` fails closed until plugin registration and callability are verified.
 - **Bounded collaboration:** an optional, explicitly controlled one-request workflow. It is not a scheduler or daemon.
 
 ## Optional integrations and support
@@ -70,7 +87,7 @@ The check runs the source policy, type checks, formatting, deterministic tests a
 
 ## Status and limits
 
-Pappra is development software (`0.1.0-beta.2`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.2`, because pre-release versions are never republished.
+Pappra is development software (`0.1.0-beta.4`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.4`, because pre-release versions are never republished.
 
 The deterministic suite covers synthetic workspaces, fixtures and local process boundaries. It does not establish real-model behavior, native host callability on every platform, CodeGraph completeness, Windows/Linux parity or production performance. A host adapter version pin is an observed support claim, not proof that a particular native installation will load or run correctly.
 

package/dist/app/doctor.js

@@ -259,7 +259,7 @@ function runtimeCheck(targetVersion, machineRuntime, passive, machinePath, obser
                 source: machinePath ?? dataDir,
                 observedAt,
                 nextActions: [
-                    'Run an explicit pappra init --apply --install-runtime with a chosen local tarball or exact version when authorized.',
+                    'Run pappra runtime install --apply (from self, tarball, or an exact version) or pappra init --apply when authorized.',
                 ],
             });
         }
@@ -335,7 +335,7 @@ function runtimeCheck(targetVersion, machineRuntime, passive, machinePath, obser
                 ]
                 : [],
             nextActions: [
-                'Run an explicit pappra init --apply --install-runtime with a chosen local tarball or exact version when authorized.',
+                'Run pappra runtime install --apply (from self, tarball, or an exact version) or pappra init --apply when authorized.',
             ],
         });
     }

package/dist/app/init.d.ts

@@ -14,6 +14,8 @@ export interface InitFailure {
     readonly message: string;
     readonly diagnostics: readonly Diagnostic[];
     readonly nextAction: string | null;
+    /** Machine-readable payload for callers that cannot prompt. */
+    readonly details?: Readonly<Record<string, unknown>>;
 }
 export interface InitRootResolution {
     readonly requestedRoot: string;
@@ -114,6 +116,8 @@ export interface PlanInitOptions {
     readonly root: string;
     readonly choices?: InitChoices | null;
     readonly runtimeVersion?: string;
+    /** Rebuilds workspace.json from selections even when a valid config exists. */
+    readonly reconfigure?: boolean;
     readonly planId?: string;
     readonly discoveredAt?: string;
     /** Reuse an immediately preceding inspectInitContext result. */
@@ -130,6 +134,30 @@ export declare function inspectInitContext(rootPath: string): Promise<InitContex
 export declare function listRepositoryCandidates(discovery: WorkspaceDiscovery): readonly RepositoryCandidate[];
 /** Lists knowledge source choices derived only from current discovery. */
 export declare function listKnowledgeCandidates(discovery: WorkspaceDiscovery): readonly KnowledgeCandidate[];
+export interface InitChoiceRule {
+    readonly field: string;
+    readonly value: string;
+    readonly reason: string;
+}
+export interface InitChoiceCandidates {
+    readonly repositories: readonly string[];
+    readonly knowledge: readonly string[];
+    readonly validation: readonly string[];
+    readonly hosts: readonly string[];
+}
+export interface DerivedInitChoices {
+    readonly choices: InitChoices;
+    readonly rules: readonly InitChoiceRule[];
+    readonly candidates: InitChoiceCandidates;
+}
+/**
+ * Derives deterministic init selections from discovery alone. Every value is
+ * reported with the rule that produced it so a caller can audit the choice
+ * before applying it; nothing here writes, installs or prompts.
+ */
+export declare function deriveInitChoices(discovery: WorkspaceDiscovery, options?: {
+    readonly pathEnv?: string;
+}): Promise<DerivedInitChoices>;
 /**
  * Produces a strict plan and exact in-memory writes. No target file is created
  * or modified by this function.