∞ HoloScript — Agent Injection Manifest

AGENT: This file is your behavioral contract for this repo. Execute the SESSION INIT sequence before any other action. All directives below are mandatory.

IDENTITY: If you are Claude, you're running in one of Joseph's surfaces (Cursor, Claude Desktop, Claude extension, or VS Code). You are not "Antigravity" — that's a separate Google IDE running Gemini. Never self-tag as antigravity in commit messages, handoffs, or HoloMesh posts. See ~/.claude/projects/C--Users-josep--ai-ecosystem/memory/feedback_antigravity-is-not-claude.md.

TEAM: You're on the HoloScript Core team. Teammates (Gemini in Antigravity IDE, Copilot in VS Code, other Claude sessions) write handoffs and knowledge — read them, utilize them, message them.

PRODUCTION: HoloScript is a production product paying users depend on. When MCP is down, investigate before falling back. When tests fail on main, fix yours / investigate pre-existing. Don't bypass safety as a shortcut.

NORTH STAR: Read NORTH_STAR.md in this repo for project-specific decisions. Read ~/.ai-ecosystem/NORTH_STAR.md for ecosystem-wide decision trees, workflow patterns, and cost thresholds. Consult BOTH before asking Joseph any architectural question — and if neither answers, PLAN, then tell Joseph what you decided and why, don't stall. GOLD Drive: Graduated vault on disk (default D:\GOLD on Windows, /mnt/d/GOLD elsewhere). Override with GOLD_ROOT. Diamond > Platinum > GOLD > knowledge store; overrides the knowledge store on conflict. Intake: INDEX.md, w_gold_034.md, wisdom/w_gold_001.md, etc. — see ~/.ai-ecosystem/CLAUDE.md (GOLD Drive).

∞ Cloud sessions (claude.ai/code)

Applies only when CLAUDE_CODE_REMOTE=true: a fresh Ubuntu VM holding a clone of GitHub main, not the laptop. Work from the laptop that was never pushed is invisible here. Where this section conflicts with the rest of the file, this section wins in the cloud.

• Missing here: the local MCP on 7411, the GOLD drive, /room and HoloMesh credentials, ~/.claude (Joseph's personal rules), and ~/.ai-ecosystem. The C:/Users/Josep/... hooks in .claude/settings.json fail harmlessly. Do not add wirings to "fix" them.
  • One repo hook does run here: .claude/hooks/validate-edit.mjs, after every Edit or Write. It is repo-relative, and it exits 2 when an edited .ts, .js, .json or HoloScript file no longer parses. The edit has already been applied by then, so treat that as a real error and fix the file.
• Use instead: for codebase questions, npx tsx packages/cli/src/cli.ts query|absorb|parse, after building the CLI's dependencies (see Setup). The "MCP unavailable, ask the user to start it" steps do not apply here: take the CLI fallback and keep going. Anything meant for the board or the room goes in the PR body, and a local seat relays it.
• Setup each session: run corepack enable && corepack prepare pnpm@9.15.9 --activate, then pnpm install --frozen-lockfile, then pnpm hooks:install.
  • On main, .githooks/pre-commit and .githooks/commit-msg are committed as 100644, and git on Linux skips a hook that is not executable. Without this step pre-commit's lint, type and secret checks never run. hooks:install sets core.hooksPath and makes pre-commit and pre-push executable, but not commit-msg, so also run chmod +x .githooks/commit-msg. Do not commit the mode change, because the fix on main is filed separately. Run both again after any checkout or merge that rewrites those files.
  • .npmrc asks for a 16 GB heap, which is the whole VM, so set npm_config_node_options=--max-old-space-size=8192 and test one package at a time.
  • Before running core tests, build core together with its dependencies, one package at a time as the root build does: corepack pnpm --workspace-concurrency=1 --filter "@holoscript/core..." run build.
  • The CLI loads its workspace dependencies from their gitignored dist/, including @holoscript/formatter and @holoscript/absorb-service. The core build does not produce them, so even parse fails with Cannot find module …/@holoscript/formatter/dist/index.js. Build the CLI's dependencies before using it: corepack pnpm --workspace-concurrency=1 --filter "@holoscript/cli..." run build, which takes about four minutes after the core build.
• Hold (2026-08-18): add no new hook files, script files or hook wirings, and that includes .claude/settings.json. Editing or deleting existing ones is fine. Environment setup belongs in the environment's setup script on claude.ai, not in the repo.
• Gates: when a pre-push gate refuses, read why and report it in the PR. Never use --no-verify, and never push by another route. Since PR #325, the doctrine-slot check (scripts/check-doctrine-slots.mjs) passes on a machine where nothing marks a HoloCI dispatch lane: no ~/.ai-ecosystem, and none of AI_ECOSYSTEM_ROOT, HOLOMESH_ROOT, AI_ECOSYSTEM_DIR, HOLOCI_WORKLOAD_PATH or HOLO_CI_WORKLOAD_PATH set.
  • Never set HOLOCI_ALLOW_MISSING_WORKLOAD, even though the check's own refusal message suggests it. The fleet's HoloCI runs this check with HOLOCI_ALLOW_MISSING_WORKLOAD=1 (ai-ecosystem scripts/holo-ci/gates.mjs). There it passes whenever no workload breadcrumb exists, and it still enforces the slots when one does. A refusal here is a finding to report, not a reason to copy that setting.
  • Test runs can create ~/.ai-ecosystem by accident: mcp-server's holoshell download tools make ~/.ai-ecosystem/holoshell/downloads unless HOLOSHELL_DOWNLOAD_SHELF is set. Set it to a temp directory before running tests.
  • If the check finds ~/.ai-ecosystem on a cloud VM, find out what created it first. An empty tree of test litter can go with cd ~ && rmdir -p .ai-ecosystem/holoshell/downloads. Use that relative path: with an absolute one, -p climbs on to your home directory and exits 1. Anything else, stop and report.
• Fleet probe: this lane is the reference that HoloCI's Jetson and Vast machines must match. A wall that blocks you (a laptop-only file, a skip, a memory limit, a missing rule) probably blocks the fleet as well, so name it in the PR body. Every receipt states the exact SHA, the Node and pnpm versions, and the exact command sequence.
• Push often: the VM is reclaimed after inactivity, and anything unpushed is lost.
• Output: one draft PR per coherent change, from a fresh claude/<topic> branch, with a title starting [provider-cloud]. Never merge, and never push to main or to another agent's branch.
  • Before any change: prove the problem exists on origin/main, search every branch for an existing fix (git log --remotes --grep=<task id>), and stay out of files an open integration PR changes.
  • Evidence includes a red leg: revert the fix and watch the test fail.
  • Write "canon not checked" in the PR. The laptop line has commits GitHub lacks.
  • End the body with the board_handoff JSON that the laptop's provider-cloud local verifier reads. It must be one flat object whose evidence_mode is board_handoff, with agent_lane, task_id, goal, files_or_sources_read, decision, incentive_provenance, validation_state, next_owner_lane and first_next_command (see #330). The verifier refuses a nested {"board_handoff": {…}}.
• Talking to Joseph: use short, plain sentences, with no code or paths. Make technical decisions yourself and say why. Only four kinds of decision go to him: spending and custody, the physical world, public statements in his name, and governance.

∞ PHASE 0 — SESSION INITIALIZATION (MANDATORY)

On every session start, execute this sequence IN ORDER:

0. GOLD DRIVE  → Before deploy/registry/wallet claims: intake GOLD Drive (`GOLD_ROOT` or default; `INDEX.md` + hot entries per ~/.ai-ecosystem/CLAUDE.md)
1. IDENTIFY    → What is the user trying to build or fix?
2. CLASSIFY    → Is this HoloScript code, tooling (TypeScript), or docs?
3. TOOL-FIRST  → If HoloScript: call suggest_traits BEFORE writing any code
4. VALIDATE    → After generation: call validate_holoscript BEFORE returning
5. AFFIRM      → Confirm output matches user intent, state what was done

Skip nothing. If MCP server is unavailable, say so explicitly and ask user to start it.

On Claude's local MCP (holoscript-local, 127.0.0.1:7411) the language tools are refused, not missing. Its loopback caller holds only tools:codebase, so suggest_traits, validate_holoscript and generate_* answer "Insufficient scope ... Granted: [tools:codebase]" through batch_tool_call (measured 2026-10-08). Steps 3 and 4 then run through the CLI, which works there: npx tsx packages/cli/src/cli.ts suggest "<description>" --json and npx tsx packages/cli/src/cli.ts parse <file> (prints "Validation successful").

∞ BEHAVIORAL OVERRIDES (HARDCODED — NEVER VIOLATE)

NEVER  → Default to React, Next.js, or conventional web patterns
NEVER  → Hand-author a NEW .tsx render/UI surface (page, panel, viewer).
         The rendered .tsx surface is FROZEN — only the grandfathered
         entries in scripts/holo-ci/render-surface-native-allowlist.json
         may be hand-written. New perceivable surfaces are authored as
         .holo and @generated to .tsx by a compiler (R3F / Native2D /
         immersive). Enforced LIVE by scripts/holo-ci/check-render-surface-native.mjs
         (pre-commit Gate 5e + HOLOSCRIPT_GATES). Grandfathering grows the
         pile the freeze exists to burn down — do not add to the allowlist.
         (D.095/D.096/W.715; RULED 2026-06-05, render-surface-native gate.)
NEVER  → Hand-write .hs/.hsplus/.holo without calling suggest_traits first
NEVER  → git add -A  or  git add .  (Windows: creates nul device file — BREAKS REPO)
NEVER  → Put a secret LITERAL on a NON-git surface. Reading a token from .env and
         placing it anywhere outside .env is a leak the git secret-scanners CANNOT
         see (the recurring 5th/6th leak lived here). Three vectors:
         (a) Railway: NEVER paste a token into registryCredentials or a raw env
             value — reference a Railway MANAGED/SEALED variable by NAME. A plaintext
             token there is readable by any holder of RAILWAY_API_TOKEN.
         (b) Shell: NEVER inline a token literal in a command (it's echoed to the
             transcript) — read it at runtime: TOKEN=$(grep '^X=' .env | cut -d= -f2).
         (c) Capture: NEVER write raw error output (curl -v, Railway/Docker/CLI
             errors, auth URLs) to a log/research/board file without scrubbing token
             patterns first (W.721 — CLIs leak keys in error URLs).
         Detect after-the-fact: node ~/.ai-ecosystem/scripts/railway-secret-audit.mjs
         (the git scanners are structurally blind to all three). (F.106, 6th
         occurrence root-caused 2026-06-16: prevention is a doctrine rule, not a tool.)
NEVER  → Create UPPERCASE .md files in docs/ root (they go in docs/_archive/)
NEVER  → Add doc pages without updating docs/.vitepress/config.ts sidebar
NEVER  → Raw curl against /api/holomesh/team/* /knowledge /message /presence
         /suggestions — use /room skill instead. Recurrent multi-agent
         antipattern; full reasoning in AGENTS.md §"⛔ ANTIPATTERN:
         raw-curl-for-room-ops". One-off endpoint-debug probes excepted.
NEVER  → On the local desktop surface: pop terminal windows (Start-Process /
         cmd /c start / Interactive scheduled tasks — S4U only), open browser
         tabs to verify anything (probe headlessly; a tab is founder-eyes-only
         on explicit request), or dump unbounded output that blanks the Claude
         Desktop app (filter at source; big artifacts → file, read slices).
         Full contract: ~/.ai-ecosystem/docs/handbooks/claude-desktop-anti-patterns.md

ALWAYS → Use .holo for cross-platform compositions
ALWAYS → Author perceivable surfaces native-first: write .holo, compile to
         .tsx with @generated provenance — never the reverse. Adding .tsx is
         allowed ONLY for tooling/CLI/parser/adapter code (never render/UI).
ALWAYS → Stage git files explicitly: git add path/to/file.ts
ALWAYS → Run pnpm test before committing
ALWAYS → Call validate_holoscript after generating any HoloScript code
ALWAYS → Add new packages to typedoc.json entryPoints
ALWAYS → Attempt MCP recovery (diagnose → start → retry) before falling back to CLI
ALWAYS → Close tasks with /room done <id> <commit> <summary> — closed
         tasks now auto-derive a tier-1.5 knowledge entry tagged
         [from-done-log, task:<id>] (confidence 0.7, type heuristic:
         gotcha/pattern/wisdom from title keywords). Founder ruling
         2026-04-30 closes the gap where done-log entries were stranded
         and never reached the GOLD pipeline. Pass --no-knowledge-sync
         (4th positional) only for trivial mechanical closes.
ALWAYS → /room for board, knowledge, messages, presence, suggestions —
         not curl. Skill handles bearer-auth, response parsing, endpoint
         shape, truncation warnings, ~5k token savings per multi-step flow.

∞ STRATEGIC DIRECTION — BRITTNEY / STUDIO FIRST

Use this doctrine when evaluating feature placement:

• Brittney is the primary intelligence interface
• Studio is the primary creation environment
• HoloScript is the general-purpose semantic systems language, substrate, and native medium
• Standard IDEs are compatibility bridges

Implications:

• Prefer building long-term intelligence accumulation for Brittney + Studio.
• Use HoloScript packages for substrate, generation, protocol, and Absorb capabilities.
• Treat IDE-focused work as transitional unless it clearly accelerates Studio adoption or HoloScript maintenance.
• When in doubt, ask whether the feature makes Studio more inevitable.

∞ DECISION TREE — Route Every Request Here

User asks for HoloScript code?
  → YES → call suggest_traits → call generate_object/generate_scene → call validate_holoscript
  → NO  ↓

User asks about a trait?
  → YES → call list_traits or explain_trait → answer from MCP result
  → NO  ↓

User asks to compile/export?
  → YES → identify target (Unity/Unreal/WebGPU/URDF/etc.) → see docs/compilers/
  → NO  ↓

User is new to HoloScript?
  → YES → direct to docs/holoschool/level-1-fundamentals/01-what-is-holoscript.md
  → NO  ↓

User is modifying TypeScript (packages/*)?
  → YES → PRE-REFACTOR: call holo_graph_status (check cache) → holo_absorb_repo (force=false uses cache)
  → THEN  → call holo_impact_analysis to find blast radius → pnpm test first → edit → pnpm test again → explicit git add
  → CLI fallback: npx tsx packages/cli/src/cli.ts query "<question>" --dir <package-path> --json
    (same canonical Absorb handlers/cache as MCP; no duplicate raw scanner)
  → NO  ↓

User is writing docs?
  → YES → lowercase filenames → add to docs/.vitepress/config.ts sidebar → NO UPPERCASE

MCP tools unavailable / tool call errors?
  → Step 1: DETECT   → any tool call returns error or tool not in schema
  → Step 2: DIAGNOSE → GET http://127.0.0.1:7411/health
  → Step 3: RECOVER  → node <AI_ECOSYSTEM>/scripts/local-service-supervisor.mjs recover holoscript-local-mcp
  → Step 4: REATTACH → retry holo_graph_status({}); if health is up but the handle is closed, reload/reconnect the MCP host
  → Step 5: FALLBACK → if this host cannot reattach, use transport-independent CLI equivalents:
       holo_absorb_repo    → npx tsx packages/cli/src/cli.ts absorb <dir> --json
       holo_query_codebase → npx tsx packages/cli/src/cli.ts query "<question>" --dir <dir> --json
       validate_holoscript → npx tsx packages/cli/src/cli.ts validate <file>
         (not `parse`: for .hs it runs a non-authoritative TS parser and passes code validate rejects)
       suggest_traits      → npx tsx packages/cli/src/cli.ts suggest "<description>" --json
       generate_*          → no CLI equivalent; skip or notify user
     The query fallback uses the canonical Absorb handlers and workspace cache, not a second scanner/index.
  → Step 6: REPORT   → distinguish service health from host-handle health

∞ MCP TOOL INJECTION — Exact Call Sequences

Generate HoloScript Object

Step 1: suggest_traits({ description: "<user's object description>" })
Step 2: generate_object({ description: "<description>", traits: <result from step 1> })
Step 3: validate_holoscript({ code: <result from step 2> })
Step 4: Return validated code

Generate Full Scene

Step 1: suggest_traits({ description: "<scene description>" })
Step 2: generate_scene({ description: "<description>", traits: <step 1 result> })
Step 3: validate_holoscript({ code: <step 2 result> })

Explain Existing Code

Step 1: parse_hs({ code: "<code>" })  OR  parse_holo({ code: "<code>" })
Step 2: explain_code({ ast: <step 1 result> })

Find Right Traits

Step 1: list_traits({ category: "<interaction|physics|visual|networking|ai|spatial|audio|iot>" })
Step 2: explain_trait({ name: "<trait name>" })

Analyze Codebase (Cache-First — Most Efficient)

Step 1: holo_graph_status({})                               → Check cache freshness (<24h = use it)
Step 2: holo_absorb_repo({ rootDir: "<pkg-path>" })        → Omit force; reads cache if fresh (~21ms)
         holo_absorb_repo({ rootDir: ".", force: true })   → Only if cache is stale or rootDir changed
Step 3: holo_query_codebase({ query: "<question>" })       → Auto-loads disk cache if needed
         holo_impact_analysis({ symbol: "<name>" })        → Blast radius (auto-loads cache)
         holo_detect_changes({ before: "ref", after: "ref" }) → Always fresh, compares two states
Step 4: holo_semantic_search / holo_ask_codebase           → Embeddings: HoloEmbed (keyless, offline — no Ollama). ask_codebase answer LLM: our own HoloLlama by default (HOLOLLAMA_ENDPOINT / HOLOLLAMA_URL); cloud or Ollama only when llmProvider names one (D.117 retired Ollama from automatic choice)

Rules:

• NEVER call holo_absorb_repo with force: true unless holo_graph_status says cache is stale
• Query tools (holo_query_codebase, holo_impact_analysis) auto-load the disk cache — no manual pre-load needed
• Results include cacheNote field showing cache age and source

MCP Tool Recovery

If any MCP tool call fails:
  1. Check server: npx tsx packages/mcp-server/src/index.ts --help
  2. Start it:     node packages/mcp-server/dist/index.js   (verified 2026-07-06; pnpm build first if dist/ is missing)
  3. Retry:        holo_graph_status({})  ← lightest possible call
  4. CLI fallback map:
     holo_absorb_repo    → npx tsx packages/cli/src/cli.ts absorb <dir> --json
     holo_query_codebase → npx tsx packages/cli/src/cli.ts query "<question>"
     validate_holoscript → npx tsx packages/cli/src/cli.ts validate <file>   (not `parse`, see above)
     suggest_traits      → npx tsx packages/cli/src/cli.ts suggest "<description>" --json
     generate_object     → no CLI equivalent (LLM-based)
  5. Notify user: "MCP server is down. Run: node packages/mcp-server/dist/index.js"

∞ KNOWLEDGE PACK — Compressed Facts

REPO        pnpm workspaces monorepo, packages/, TypeScript + vitest + tsup
TRAITS      count: find packages/core/src/traits -name "*.ts" | wc -l; categories: ls packages/core/src/traits/constants/ — ALL in @holoscript/core (no separate package)
COMPILERS   count: find packages/core/src -name "*Compiler.ts" | wc -l — ALL in @holoscript/core (no separate @holoscript/compiler)
MCP         packages/mcp-server/ — tool count: GET https://mcp.holoscript.net/health → tools field — start with: npx tsx packages/mcp-server/src/index.ts
CACHE       ~/.holoscript/graph-cache.json — 24h TTL — holo_absorb_repo force=false reads from cache (~21ms)
BRITTNEY    ../Hololand/packages/brittney/mcp-server/ — runtime AI, optional
TEST        pnpm test | pnpm test --filter @holoscript/core | createComposition() pattern
BUILD       pnpm build | pre-commit: ESLint + tsc + tests (auto-runs)
WINDOWS     git add -A creates nul file — ALWAYS explicit: git add specific/file.ts
DOCS        docs/.vitepress/config.ts controls ALL navigation — update sidebar on every new page
ARCHIVE     UPPERCASE .md → docs/_archive/ | lowercase .md → docs/[section]/

Packages Quick Map

@holoscript/core             Parser · AST · traits · compilers (counts via find packages/core/src; see docs/NUMBERS.md)
@holoscript/mcp-server       AI tools (parse, validate, generate, compile, codebase intelligence — count via GET mcp.holoscript.net/health)
@holoscript/cli              holo build · holo compile · holo validate
@holoscript/runtime          Scene execution runtime
@holoscript/lsp              Language Server Protocol (VS Code, Neovim)
@holoscript/formatter        Code formatter
@holoscript/linter           Linting rules
@holoscript/llm-provider     OpenAI · Anthropic · Gemini unified SDK
@holoscript/security-sandbox vm2-based execution sandbox
@holoscript/ai-validator     Hallucination detection (Levenshtein distance)
@holoscript/partner-sdk      Webhooks · analytics · partner APIs
holoscript (PyPI)            Python bindings + robotics module

File Format Decision Matrix

Situation                                    → Use
Logic, process, pipeline, or headless program → .hs
Typed behavior, agent, effect, or trait program → .hsplus
Whole-system composition / cross-target orchestration → .holo
Perceivable render/UI surface (page/panel/viewer) → .holo (→ @generated .tsx; NEVER hand-author .tsx)
Bootstrap tooling not yet expressible in HoloScript → .ts / Rust with an explicit migration seam

Trait Category Index

interaction   @grabbable @throwable @clickable @hoverable @draggable @pointable @scalable
physics       @collidable @physics @rigid @kinematic @trigger @gravity @soft_body
visual        @glowing @emissive @transparent @reflective @animated @billboard @particle
networking    @networked @synced @persistent @owned @host_only @replicated
ai-behavior   @npc @pathfinding @llm_agent @reactive @state_machine @crowd
spatial       @anchor @tracked @world_locked @hand_tracked @eye_tracked @plane_detected
audio         @spatial_audio @ambient @voice_activated @reverb @doppler
accessibility @high_contrast @screen_reader @reduced_motion @voice_nav
web3          @nft_asset @token_gated @wallet_connected @on_chain
media         @video_surface @live_stream @screen_share @360_video
iot           @iot_sensor @digital_twin @mqtt_bridge @telemetry
social        @avatar @presence @voice_chat @emote @proximity_chat
advanced      @shader_custom @compute_shader @ray_traced @lod_managed

∞ DOCS STRUCTURE — Where Things Live

docs/holoschool/       25 lessons, 3 levels (newcomer entry point)
docs/compilers/        targets (count via `ls docs/compilers/`): unity/ unreal/ godot/ vrchat/ webgpu/ ios/ vision-os/
                       android/ android-xr/ openxr/ openxr-spatial/ robotics/urdf robotics/sdf
                       iot/dtdl iot/wot playcanvas/ wasm/ ar/ tsl/ neuromorphic/ a2a/ scm/
                       usd-physics/ ai-glasses/ vr-reality/ nft-marketplace/
docs/traits/           category pages (count via `ls docs/traits/`) + index + extending guide
docs/agents/           uAA2++ agent framework, UAAL VM
docs/guides/           Core concepts, mcp-server, installation, best-practices
docs/integrations/     Hololand, Grok/xAI, AI architecture, interoperability
docs/cookbook/         Copy-paste recipes (vr-world, robotics, ai-world, multi-agent)
docs/language/         Language spec, syntax extensions
docs/api/              TypeDoc auto-generated (run: pnpm typedoc)
docs/examples/         hello-world, arena-game, world-builder
docs/_archive/         Dev notes, phase guides, session notes (NOT user-facing)

∞ AFFIRMATION PROTOCOL — Before Reporting Done

□ Did I call validate_holoscript on all generated HoloScript code?
□ Did I run pnpm test if I modified any TypeScript?
□ Did I call holo_graph_status then holo_absorb_repo BEFORE refactoring ANY TypeScript package?
□ If any MCP tool failed, did I attempt recovery (diagnose → start → retry) before falling back to CLI?
□ Did I use explicit git add (never git add -A)?
□ Did I update docs/.vitepress/config.ts if I created a new doc page?
□ Does the output match what the user actually asked for?
□ Did I state clearly what I created/changed and why?

If any box is unchecked → complete that step before responding.

∞ NEWCOMER FAST PATH

0. docs/storefront/index.md                                      (Language + admit + crew + pay windows)
0b. C:/holo-dev/ai-ecosystem/docs/storefront/local.md             (Vehicle people ride)
0c. C:/holo-dev/HoloRepo/Hololand/docs/storefront/local.md        (Worlds store)
0d. C:/holo-dev/ai-ecosystem/docs/storefront/mind.md              (Mind store)
1. docs/holoschool/level-1-fundamentals/01-what-is-holoscript.md  (What + Why — still VR-flavored until V1 gate)
2. docs/holoschool/level-1-fundamentals/02-installation.md        (Setup)
3. docs/holoschool/level-1-fundamentals/03-first-scene.md         (First .holo)
4. docs/traits/index.md                                          (Superpower)
5. docs/compilers/index.md                                       (Deploy)

GitHub README.md is not the V1 storefront until docs/storefront/github-v1-gate.md is green.

∞ CONTRIBUTING CONTRACT

• UPPERCASE .md files → docs/_archive/ only
• Every new doc page → add entry to docs/.vitepress/config.ts sidebar
• New packages → add to typedoc.json entryPoints
• All tests must pass before commit
• Plan Completeness Gap Reporting: Every technical plan MUST end with an honest "What Remains After This Plan" section that clearly lays out the real-world usability or feature gaps that are deliberately left unaddressed, preventing agents from prematurely concluding that a major initiative is "finished".
• See CONTRIBUTING.md for full AI Agent Documentation Standards

HoloScript Absorb — Codebase Intelligence

Codebase intelligence for this repo runs on the sovereign local MCP (http://127.0.0.1:7411/mcp — R.027; start with PORT=7411 node packages/mcp-server/dist/http-server.js). Run holo_graph_status there for current symbol / relationship / execution-flow counts. absorb.holoscript.net is the public remote Absorb service for remote repos — it cannot see this working tree, so never route this repo's absorption there.

PORT=7411 is required and was missing from this command until 2026-08-03. http-server.ts defaults to process.env.PORT || '3000', so the bare command starts the server on 3000 while every doc, probe and recovery step here targets 7411. The result was silent and repo-wide: agents probed 7411, got ECONNREFUSED, concluded "local MCP is down", and fell through to the cloud instance — which is FS-blind to this machine and answers successfully about its own container /tmp, complete with a stale graph carrying cache_root_mismatch. A confidently wrong answer about the wrong filesystem is worse than a refusal. If you ever see codebase-intelligence results that do not match the working tree, check which endpoint answered first.

Always Start Here

1. Call holo_graph_status({}) — check cache freshness (<24h = use it)
2. Match your task to a skill below and read that skill file
3. Follow the skill's workflow and checklist

If step 1 reports stale / missing cache, call holo_absorb_repo({ rootDir: ".", force: true }) first. CLI fallback: npx tsx packages/cli/src/cli.ts absorb . --json.

Skills

Verified state 2026-04-27 (absorb-service): the HoloScript MCP server at mcp.holoscript.net returns 200 on /health and the holo_* codebase intelligence tools ARE callable. Absorb (absorb.holoscript.net) routes are defined in-repo (services/absorb-service/src/server.ts); Liveness: GET /health and GET /mcp (SSE) are the reliable production probes. REST under /api/... has been blocked or inconsistent in live deploys (authenticated probes returning 404 — board task*1777164270247_7ee8, deploy stack). Do not assume curl https://absorb.holoscript.net/api/... works in production until a probe returns 2xx. Prefer **holo*\*tools onmcp.holoscript.net**, local packages/cliabsorb, orRead+Grepover betting on live absorb REST. Client middleware fix (2026-04-27):authanonymousPOSTscan now matches mount-relativereq.pathfor/api/absorb/scan so that route is reachable when the app actually serves it.