manifest.json

{
  "name": "nddev-zcode-app",
  "build_version": "0.1.3",
  "source_root": "zcode_tools/marketplaces/",
  "installer": "cli-tools/scripts/install.sh install",
  "layout": {
    "zcode_tools/marketplaces/nddev-builder/": "the managed native marketplace that builds the default full-auto ZCode home",
    "cli-tools/": "setup manager: install builds the managed setup by default; --setup nddev-builder/--marketplace nddev-builder remain compatibility selectors (macOS + Ubuntu)",
    "build/": "build contracts: version.json, manifest.json, and the local secrets template shared by the managed setup",
    "config/": "public repository and release contract metadata",
    "references/": "verified public ZCode compatibility baseline",
    "docs/": "public installation, architecture, and secrets documentation",
    ".github/": "public security, release, and repository-automation workflows"
  },
  "runtime_bundle": {
    "_comment": "Minimal runtime distribution closure: the tracked paths required to install ZCode from the managed setup, including the canonical repository instructions and Claude bridge while excluding CI and source-level documentation. A release may publish this as a second, attested bundle distinct from the full source archive.",
    "paths": [
      "VERSION",
      "LICENSE",
      "NOTICE",
      "README.md",
      "AGENTS.md",
      ".claude",
      "build",
      "cli-tools",
      "config",
      "references",
      "zcode_tools"
    ]
  },
  "artifact_integrity_policy": {
    "metadata_source": "build/version.json:zcode_download_artifacts",
    "canonical_cdn_base": "https://cdn-zcode.z.ai/zcode/electron/releases",
    "required_before_install": [
      "exact filename",
      "exact byte size",
      "SHA-512 digest"
    ],
    "macos_identity": "official ZIP artifact only, exact Team ID/bundle ID/app version/bundle version, deep/strict code signature, and per-artifact Gatekeeper source from build/version.json; pinned unnotarized artifacts, if ever declared, fail closed unless bootstrap is run with --allow-pinned-unnotarized",
    "debian_identity": "before install: exact package metadata plus one safe /opt/ZCode/resources/glm/zcode.cjs payload entry with the pinned CLI version; after install: exact dpkg-owned path/version and byte-identical CLI SHA-512",
    "appimage_identity": "exact filename, byte size, SHA-512 digest, embedded CLI version, and installed version marker"
  },
  "bootstrap_policy": {
    "locking": "deterministically ordered locks protect each managed application endpoint and the user launcher; dpkg retains ownership of its system package transaction",
    "debian_preflight": "dpkg --dry-run -i must succeed before the real dpkg -i transaction",
    "commit_point": "exact app, package, entrypoint, launcher, and CLI postconditions define a committed bootstrap",
    "cleanup_after_commit": "cleanup failure after verified runtime visibility is reported as cleanup_pending=true and exits success without rolling back a verified committed app or launcher",
    "cleanup_before_commit": "errors and handled signals roll back staged app and launcher swaps where recovery state is unambiguous"
  },
  "command_option_policy": {
    "bootstrap": [
      "--platform",
      "--apply",
      "--plan",
      "--dry-run",
      "--allow-pinned-unnotarized"
    ],
    "install": [
      "--setup",
      "--marketplace",
      "--posture",
      "--target",
      "--platform",
      "--apply",
      "--plan",
      "--dry-run",
      "--adopt-unmanaged"
    ],
    "remove": [
      "--target",
      "--apply",
      "--plan",
      "--dry-run",
      "--keep-backup"
    ],
    "restore": [
      "--slot",
      "--target",
      "--apply",
      "--plan",
      "--dry-run",
      "--allow-target-relocation"
    ],
    "list": [
      "-l",
      "--list",
      "--backups",
      "--json"
    ],
    "status": [
      "--target",
      "--json"
    ],
    "invalid_combination": "unknown, command-inapplicable, and mutually exclusive mode options are rejected instead of ignored"
  },
  "setup_state_policy": {
    "catalog_identity": "the managed setup catalog contains nddev-builder; safe kebab-case directory id must equal marketplace.json:name",
    "default_setup": "nddev-builder",
    "selection_option": "install defaults to nddev-builder; --setup nddev-builder and --marketplace nddev-builder remain backward-compatible aliases",
    "plugin_contract": "runtime selection validates a safe self-contained tree; plugin names match [a-z0-9][a-z0-9._-]{0,127}; names and exact ./plugins/<name> sources are unique; marketplace entries, SemVer versions, plugin manifests, and declared directories match before plan or apply mutation",
    "posture_option": "--posture full-auto|safe, default full-auto",
    "new_stamp_schema": 2,
    "new_stamp_identity": "BUILD-VERSION.setup_id must equal nddev-builder; BUILD-VERSION.posture records the selected posture",
    "legacy_recovery": "schema 0 and 1 stamps remain readable for backup, restore, remove, and status; their setup identity is reported as unknown",
    "machine_interfaces": [
      "list --json",
      "status --json"
    ]
  },
  "runtime_probe_policy": {
    "resolution": "resolve and canonicalize one executable before invoking it",
    "timeout_seconds": 30,
    "max_output_bytes": 65536,
    "advisory_failure": "timeout, nonzero exit, excessive output, decode/runtime error, or missing executable becomes unknown/not-installed without aborting install",
    "bootstrap_postcondition": "bootstrap remains strict and rejects an unknown or mismatched CLI version"
  },
  "model_provider_policy": {
    "cli_bootstrap": "every setup declares an explicit provider/model main reference and matching provider kind, options.baseURL, and model metadata",
    "oauth_boundary": "the CLI bootstrap is secret-free; ZCode supplies restored account OAuth credentials through its runtime provider registry",
    "custom_provider_identity": "explicit API-key providers use custom:* identities and never reuse ZCode-owned builtin:* ids",
    "validation": "plan and apply fail closed on a missing or inconsistent CLI model/provider bootstrap or a reserved builtin:* identity on a custom provider"
  },
  "version_policy": {
    "syntax": "SemVer 2.0.0 for module, runtime, managed-stamp, adopted-envelope, and backup-name versions",
    "release_lockstep": [
      "VERSION",
      "build/version.json:build_version",
      "build/manifest.json:build_version",
      "zcode_tools/marketplaces/nddev-builder/marketplace.json:plugins[name=core].version",
      "zcode_tools/marketplaces/nddev-builder/plugins/core/.zcode-plugin/plugin.json:version"
    ],
    "release_lineage": "the tagged commit must be an ancestor of freshly fetched origin/main"
  },
  "backup_policy": {
    "location": "~/.zcode-backups/",
    "name_format": "<N>-<VERSION>-old.zcode (N = slot 0-9; VERSION is validated SemVer, or unmanaged only for explicit adoption)",
    "max_backups": 10,
    "rotation": "lowest free slot 0-9; oldest (by mtime) overwritten when full, regardless of version",
    "version_source": "validated <target>/BUILD-VERSION for managed targets",
    "adopted_unmanaged_envelope": "<N>-unmanaged-old.zcode/{NDDEV-BACKUP.json,payload/}",
    "inventory": "list --backups is a no-create backup-resource read; it validates complete managed stamps and adopted envelopes before display, preserves valid historical SemVer/timestamps, and emits fixed redacted classifications without echoing malformed names or metadata"
  },
  "transaction_policy": {
    "path_boundaries": "target and backup path values reject ASCII C0 controls (U+0000-U+001F) and DEL (U+007F) before coordination or filesystem mutation while preserving spaces, Unicode, and relative-path resolution; canonical non-root target and backup roots must be disjoint absent-or-real-directory endpoints on one filesystem",
    "safe_tree": "managed inputs reject symlinks, special files, and multiply-linked regular files",
    "locking": "one role-independent canonical-path digest and legacy-byte-compatible target marker identify target and backup resources; mutators hold product EX through the complete lifecycle, first quiesce every bounded existing path anchor for mixed-version safety, then hold the deterministic sorted target, requested-backup, and exact-snapshot pending-backup resource set through commit and recovery; status reads target only, plan reads target/requested/pending resources, and list --backups reads backup only without anchor creation or repair; status and plan expose the compatible product and target anchor paths/states plus bounded cleanup_pending metadata without cleanup deletion paths",
    "runtime_quiescence": "apply-mode target mutations reject open task/session databases and SQLite recovery sidecars; ZCode must be quit cleanly before setup changes",
    "staging": "render, restore selected state, normalize permissions, verify, and fsync a same-filesystem sibling stage before live replacement",
    "commit": "write durable live-rename prepare authority before the first live move, move the previous target into its backup when present, then atomically rename the verified stage without replacement; before removing durable authority, revalidate the final target, rollback source, retired slot, complete graphs, journal binding, and parent identities at the actual commit decision",
    "rollback": "recover or fail closed from durable live-rename prepare and cleanup journal state under fd-bound no-follow cleanup namespace authority and all bound resource locks; identity, graph, journal, or parent mismatch preserves foreign state and durable recovery authority; valid post-commit cleanup failure is reported as cleanup_pending without discarding committed state",
    "hard_interruption": "SIGKILL or power loss is recovered from bounded prepare/journal authority by the next coordinated lifecycle operation, or reported as deterministic operator action when state is incoherent"
  },
  "adoption_policy": {
    "authorization": "--adopt-unmanaged requires install with an explicit existing --target",
    "backup": "the original unstamped content tree is stored inside a typed adopted-unmanaged envelope with permissions normalized to private owner-only modes",
    "marker": {
      "schema": 1,
      "exact_keys": [
        "schema",
        "type",
        "original_target",
        "created_at",
        "installer_build",
        "payload"
      ],
      "installer_build": "canonical SemVer 2.0.0; restore accepts valid historical builds",
      "created_at_format": "canonical UTC YYYY-MM-DDTHH:MM:SSZ with second precision",
      "original_target": "ASCII C0/DEL-free canonical absolute non-root path",
      "validation_order": "the complete marker is validated before target binding or relocation authorization"
    },
    "restore": "the validated original target is enforced; relocation requires restore with explicit absolute --target and --allow-target-relocation"
  },
  "restore_policy": {
    "always_restore": [
      "v2/credentials.json",
      "v2/certs/",
      "v2/tasks-index.sqlite",
      "v2/sessions/",
      "v2/bot-config.json",
      "v2/bot-state.json",
      "v2/bot-state.v2.json",
      "cli/agents/",
      "cli/db/",
      "cli/artifacts/"
    ],
    "never_restore": [
      "cli/log/",
      "cli/exec/",
      "cli/rollout/",
      "v2/logs/",
      "v2/crash/",
      "cli/plugins/cache/",
      "v2/bots-model-cache.json",
      "v2/bots-model-cache.v2.json",
      "v2/coding-plan-cache.json",
      "v2/telemetry-state.json"
    ]
  },
  "secrets": {
    "template": "build/.env.example",
    "real": "build/.env (gitignored)",
    "source_requirements": "build/.env must be a current-user-owned regular non-symlink file with no group/world permission bits (0600 or stricter)",
    "path_expansion": "only ZCODE_TARGET and ZCODE_BACKUPS_DIR expand an exact leading literal $HOME, $HOME/, ${HOME}, or ${HOME}/ prefix; no shell evaluation or general expansion",
    "injection": "Only keys declared by build/.env.example or referenced in selected marketplace JSON string values are imported from the process environment; process values override build/.env values in one immutable snapshot shared by target/backup resolution, plan, and apply. ${VAR} placeholders are resolved for plan validation and JSON-escaped during apply rendering; placeholder-bearing object keys are rejected",
    "rendering": "plan and apply reject invalid JSON with its input path, strip top-level _comment metadata from rendered inputs, and reject placeholder-bearing object keys after hooks/MCP merge with exact logical paths across active and disabled branches",
    "active_placeholder_validation": "plan and apply reject missing/empty placeholders in keys or values across active config, setting, provider, MCP, and hook branches; explicitly disabled providers/MCP servers may remain dormant",
    "runtime_locations": [
      "<target>/.env",
      "<target>/cli/config.json",
      "<target>/v2/config.json",
      "<target>/v2/credentials.json",
      "<backups>/"
    ],
    "permissions": "target and backup trees are private to the current user; rendered secret-bearing files use owner-only permissions"
  }
}