docs: clarify adoption and daily project workflow

NON_CLAIMS.md

@@ -36,13 +36,15 @@ This repository state does not claim:
 Consuming repositories must keep their own specifications, proof bindings,
 native witnesses, CI gates, rollback policy, and rollout decisions.
 
-Phase5A integration source/check implements only bounded portable generation
-and read-only generated-byte freshness. It does not install, update, remove,
-repair, activate host instructions, grant tool permissions, or authorize native
-execution. Phase5B managed lifecycle remains open; manual shell export does not
-close it. `current` neither proves semantic full proof nor guarantees stability
-after return. Consumed registered-contract identity is not complete transitive
-native-semantic identity, and byte budgets are not token counts.
+Integration source/check provides bounded portable generation and read-only
+generated-byte freshness. Managed integration plan/apply/recover provides
+explicit install, update, removal and recovery through the repository
+transaction owner. Neither proves host instruction discovery or activation,
+grants tool permissions, or authorizes native execution. Manual shell export
+does not prove native-host integration. `current` neither proves semantic full
+proof nor guarantees stability after return. Consumed registered-contract
+identity is not complete transitive native-semantic identity, and byte budgets
+are not token counts.
 
 Declared witness routes do not prove execution. Installed npm/Python integration
 smokes and final frozen-tree closure require actual execution against the named

internal/tools/packageverify/main.go

@@ -286,7 +286,7 @@ func verifyPackedPlatformBinariesMatchSource(artifact rootPackageArtifact) error
 
 func sourceOwnedPackageEntry(entry string) bool {
 	switch entry {
-	case "package/LICENSE", "package/dist/agentic-proofkit", "package/package.json":
+	case "package/LICENSE", "package/dist/agentic-proofkit", "package/package.json", workspaceImageEntry:
 		return true
 	default:
 		return packageTextEntry(entry)
@@ -324,7 +324,11 @@ func verifyRootPackage(record packRecord) (rootPackageArtifact, error) {
 			return rootPackageArtifact{}, fmt.Errorf("root package contains unexpected entry %s", entry)
 		}
 	}
-	return rootPackageArtifact{Content: content, Entries: entries, Headers: entryHeaders, Record: record}, nil
+	artifact := rootPackageArtifact{Content: content, Entries: entries, Headers: entryHeaders, Record: record}
+	if err := verifyPackedWorkspaceImage(artifact); err != nil {
+		return rootPackageArtifact{}, err
+	}
+	return artifact, nil
 }
 
 func verifyPackRecordBytes(record packRecord) error {
@@ -357,6 +361,7 @@ func requiredRootEntries() []string {
 		"package/README.md",
 		"package/SECURITY.md",
 		"package/dist/agentic-proofkit",
+		workspaceImageEntry,
 		"package/docs/proofkit-contract-map.md",
 		"package/docs/release-process.md",
 		"package/package.json",
@@ -461,6 +466,9 @@ func verifyTarEntryHeader(entry tarEntry) error {
 	if entry.Size < 0 || entry.Size > maxTarEntryBytes {
 		return fmt.Errorf("root package tar entry %s has invalid size %d", entry.Name, entry.Size)
 	}
+	if entry.Name == workspaceImageEntry && (entry.Size == 0 || entry.Size > maxWorkspaceImageBytes || entry.Mode != 0o644) {
+		return fmt.Errorf("root package workspace image requires bounded non-empty bytes and mode 0644")
+	}
 	if rootBinaryEntry(entry.Name) {
 		if entry.Size == 0 || entry.Size > maxEmbeddedBinaryBytes {
 			return fmt.Errorf("root package binary entry %s has invalid size %d", entry.Name, entry.Size)
@@ -570,6 +578,7 @@ func forbiddenRootEntry(path string) bool {
 
 func allowedRootEntry(path string) bool {
 	allowedExact := map[string]struct{}{
+		workspaceImageEntry:                                                          {},
 		"package/ADOPTION.md":                                                        {},
 		"package/LICENSE":                                                            {},
 		"package/NON_CLAIMS.md":                                                      {},
@@ -677,6 +686,7 @@ func verifyRootManifestBoundary(artifact rootPackageArtifact) error {
 		"README.md",
 		"SECURITY.md",
 		"dist/**",
+		"docs/images/workspace.png",
 		"docs/proofkit-contract-map.md",
 		"docs/release-process.md",
 		"docs/specs/**/*",
@@ -2646,7 +2656,7 @@ func verifyInstalledJSONABI(consumer string) error {
 	if err := verifyInstalledNPMWorkflowSmoke(consumer); err != nil {
 		return fmt.Errorf("outside consumer agent-workflow smoke failed: %w", err)
 	}
-	return nil
+	return verifyInstalledREADMEWorkflow(consumer)
 }
 
 func verifyInstalledAgentRouteEnvelopeModes(consumer string) error {

internal/tools/packageverify/main_test.go

@@ -87,6 +87,7 @@ func TestVerifyPackedOwnerRecordsRejectsSourceArtifactContentDrift(t *testing.T)
 	withWorkingDirectory(t, root)
 	entries := []string{
 		"package/LICENSE",
+		"package/docs/images/workspace.png",
 		"package/dist/agentic-proofkit",
 		"package/package.json",
 		"package/docs/specs/example/requirements.v1.json",
@@ -881,7 +882,10 @@ func TestExactTarballOnboardingTrace(t *testing.T) {
 		if err := snapshot.Verify(consumer); err != nil {
 			return err
 		}
-		return verifyInstalledOnboardingTraceWithCarrier(consumer, snapshot.Contract, snapshot.Readme, runInstalledWithInput, runInstalledBinaryWithInput)
+		if err := verifyInstalledOnboardingTraceWithCarrier(consumer, snapshot.Contract, snapshot.Readme, runInstalledWithInput, runInstalledBinaryWithInput); err != nil {
+			return err
+		}
+		return verifyInstalledREADMEWorkflow(consumer)
 	}); err != nil {
 		t.Fatalf("exact tarball onboarding trace failed: %v", err)
 	}
@@ -2057,6 +2061,7 @@ func packageManifestFixture(repositoryURL string) string {
     "README.md",
     "SECURITY.md",
     "dist/**",
+    "docs/images/workspace.png",
     "docs/proofkit-contract-map.md",
     "docs/release-process.md",
     "docs/specs/**/*",

internal/tools/packageverify/readme_workflow.go

@@ -0,0 +1,90 @@
+package main
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func installedREADMEWorkflowRoutes(content string) ([]string, error) {
+	blocks := []struct {
+		name     string
+		premise  string
+		commands []string
+	}{
+		{"first-action", "", []string{"adopt plan --repo-root . --mode audit-from-code --format text"}},
+		{"daily-workflow", "For an already materialized, current project:", []string{
+			"status --repo-root . --format text",
+			"next --repo-root . --format text",
+			"view --repo-root . --serve",
+		}},
+	}
+	for _, block := range blocks {
+		startMarker := "<!-- proofkit:" + block.name + ":start -->"
+		endMarker := "<!-- proofkit:" + block.name + ":end -->"
+		if strings.Count(content, startMarker) != 1 || strings.Count(content, endMarker) != 1 {
+			return nil, fmt.Errorf("installed README workflow markers must occur exactly once")
+		}
+		start := strings.Index(content, startMarker) + len(startMarker)
+		end := strings.Index(content, endMarker)
+		if end <= start {
+			return nil, fmt.Errorf("installed README workflow marker order is invalid")
+		}
+		lines := []string{"```bash"}
+		if block.premise != "" {
+			lines = append([]string{block.premise, ""}, lines...)
+		}
+		for _, command := range block.commands {
+			lines = append(lines, installedNPMExecCommandPrefix+command)
+		}
+		lines = append(lines, "```")
+		if strings.TrimSpace(content[start:end]) != strings.Join(lines, "\n") {
+			return nil, fmt.Errorf("installed README workflow must preserve its prerequisite and exact commands")
+		}
+	}
+	return strings.Fields(blocks[0].commands[0]), nil
+}
+
+func verifyInstalledREADMEWorkflow(consumer string) (returnErr error) {
+	readme, err := os.ReadFile(filepath.Join(consumer, filepath.FromSlash(installedNPMPackageRelativeRoot), installedNPMReadmeRelativePath))
+	if err != nil {
+		return fmt.Errorf("read installed README workflow: %w", err)
+	}
+	args, err := installedREADMEWorkflowRoutes(string(readme))
+	if err != nil {
+		return err
+	}
+	// The empty child still resolves the installed npm dependency from its parent.
+	root, err := os.MkdirTemp(consumer, "readme-first-action-")
+	if err != nil {
+		return fmt.Errorf("create README first-action repository: %w", err)
+	}
+	defer func() { returnErr = errors.Join(returnErr, os.RemoveAll(root)) }()
+	result, err := runInstalledWithInput(root, nil, args...)
+	if err != nil {
+		return fmt.Errorf("execute installed README first action: %w", err)
+	}
+	if result.ExitCode != 0 || len(result.Stderr) != 0 || bytes.Contains(result.Stdout, []byte("\x1b")) || len(result.Stdout) > 32<<10 {
+		return fmt.Errorf("installed README first action must produce bounded successful uncolored text")
+	}
+	for _, line := range []string{
+		"Adoption plan", "Mode: audit-from-code", "State: authoring_required",
+		"Inventory: 0 recognized, 0 omitted, 0 opaque", "Authority: candidate-only; consuming repository owner",
+		"Evidence template: native-evidence-guidance",
+	} {
+		if !strings.Contains("\n"+string(result.Stdout), "\n"+line+"\n") {
+			return fmt.Errorf("installed README first action lost its candidate-only empty-repository outcome")
+		}
+	}
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		return fmt.Errorf("inspect README first-action repository: %w", err)
+	}
+	if len(entries) != 0 {
+		return fmt.Errorf("installed README first action must not materialize repository files")
+	}
+	return nil
+}

internal/tools/packageverify/readme_workflow_test.go

@@ -0,0 +1,46 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+)
+
+func TestREADMEWorkflowRoutes(t *testing.T) {
+	t.Parallel()
+	content, err := os.ReadFile(filepath.Join("..", "..", "..", "README.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	readme := string(content)
+	args, err := installedREADMEWorkflowRoutes(readme)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !slices.Equal(args, []string{"adopt", "plan", "--repo-root", ".", "--mode", "audit-from-code", "--format", "text"}) {
+		t.Fatal("README first action changed its read-only root and trust mode")
+	}
+	for _, pair := range [][2]string{
+		{"adopt plan --repo-root .", "adopt materialize apply --repo-root ."},
+		{"--mode audit-from-code", "--mode code-baseline"},
+		{"status --repo-root . --format text", "status --repo-root ."},
+		{"next --repo-root . --format text", "status --repo-root . --format text"},
+		{"view --repo-root . --serve", "view --repo-root ."},
+		{"view --repo-root . --serve", "view --repo-root . --serve --open"},
+		{"For an already materialized, current project:", ""},
+		{"For an already materialized, current project:", "Immediately after the read-only plan, run:"},
+		{"<!-- proofkit:first-action:start -->", ""},
+		{"<!-- proofkit:first-action:end -->", "<!-- proofkit:first-action:start -->"},
+		{"<!-- proofkit:daily-workflow:end -->", "<!-- proofkit:daily-workflow:end -->\n<!-- proofkit:daily-workflow:end -->"},
+		{"npm exec --offline -- agentic-proofkit adopt", "npx agentic-proofkit adopt"},
+	} {
+		if !strings.Contains(readme, pair[0]) {
+			t.Fatal("README route mutation missed its subject")
+		}
+		if _, err := installedREADMEWorkflowRoutes(strings.ReplaceAll(readme, pair[0], pair[1])); err == nil {
+			t.Fatal("mutated README workflow admitted")
+		}
+	}
+}

internal/tools/packageverify/workspace_image.go

@@ -0,0 +1,40 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"image/png"
+)
+
+const (
+	workspaceImageEntry     = "package/docs/images/workspace.png"
+	maxWorkspaceImageBytes  = 2 << 20
+	maxWorkspaceImageWidth  = 2048
+	maxWorkspaceImageHeight = 1536
+)
+
+func verifyPackedWorkspaceImage(artifact rootPackageArtifact) error {
+	content, err := readTarFileFromBytes(artifact.Content, workspaceImageEntry)
+	if err != nil {
+		return err
+	}
+	return verifyWorkspaceImage(content)
+}
+
+func verifyWorkspaceImage(content []byte) error {
+	if len(content) == 0 || len(content) > maxWorkspaceImageBytes {
+		return fmt.Errorf("root package workspace image exceeds its byte bounds")
+	}
+	config, err := png.DecodeConfig(bytes.NewReader(content))
+	if err != nil {
+		return fmt.Errorf("root package workspace image has invalid PNG metadata")
+	}
+	// Dimensions bound allocation independently of the compressed byte count.
+	if config.Width < 1 || config.Width > maxWorkspaceImageWidth || config.Height < 1 || config.Height > maxWorkspaceImageHeight {
+		return fmt.Errorf("root package workspace image exceeds its dimension bounds")
+	}
+	if _, err := png.Decode(bytes.NewReader(content)); err != nil {
+		return fmt.Errorf("root package workspace image is not a complete PNG")
+	}
+	return nil
+}