@maxkle1nz/m1nd 0.9.0-beta.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@maxkle1nz/m1nd",
+  "version": "0.9.0-beta.0",
+  "description": "Universal installer and agent pack for the m1nd MCP runtime.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maxkle1nz/m1nd.git"
+  },
+  "homepage": "https://github.com/maxkle1nz/m1nd#readme",
+  "bugs": {
+    "url": "https://github.com/maxkle1nz/m1nd/issues"
+  },
+  "type": "commonjs",
+  "bin": {
+    "m1nd": "npm/bin/m1nd.js"
+  },
+  "files": [
+    "npm/",
+    "skills/README.md",
+    "skills/m1nd-universal-agent-pack.md",
+    "skills/m1nd-first/SKILL.md",
+    "skills/m1nd-operator/SKILL.md",
+    "skills/m1nd-operator/references/*.md",
+    "skills/m1nd-operator/scripts/probe_m1nd.py",
+    "docs/AGENT-PACKS.md",
+    "docs/AGENT-FIRST-DEMO.md",
+    "docs/MCP-HOST-REFRESH.md",
+    "docs/IDE-INTEGRATIONS.md",
+    "README.md",
+    "EXAMPLES.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test npm/test/cli.test.js",
+    "m1nd:doctor": "node npm/bin/m1nd.js doctor",
+    "m1nd:pack-check": "node npm/bin/m1nd.js pack-check",
+    "m1nd:install-generic": "node npm/bin/m1nd.js install-skills generic --project .",
+    "test:npm": "node --test npm/test/cli.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/README.md

@@ -0,0 +1,26 @@
+# m1nd Agent Skills
+
+This directory is the installable agent doctrine for `m1nd`.
+
+It is intentionally host-neutral:
+
+- `m1nd-first` is the short rule set agents should load before repository work.
+- `m1nd-operator` is the deeper operating manual for routing, recovery, `L1GHT`,
+  document binding, multi-agent coordination, and runtime refresh.
+- `m1nd-universal-agent-pack.md` is the portable prompt-pack form for hosts that
+  do not have a native skill directory.
+
+Use the npm installer from the repo root to install the right shape:
+
+```bash
+npm install -g .
+m1nd install-skills codex
+m1nd install-skills generic --project /path/to/project
+```
+
+For a published package, the same flow becomes:
+
+```bash
+npm install -g @maxkle1nz/m1nd@beta
+m1nd init --host codex
+```

package/skills/m1nd-first/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: m1nd-first
+description: Use when investigating a repository, searching for implementation, reviewing changes, working from specs/docs, or preparing a risky code change in an environment where m1nd is available. This doctrine makes m1nd the first investigative layer before grep, glob, or manual file reads, except when the task is pure compiler/runtime truth or the exact file and lines are already known.
+---
+
+# m1nd-first
+
+This is a doctrine, not a manual.
+
+## Rules
+
+- Start with `m1nd`.
+- Before `rg`, shell globbing, or manual file reads, first ask whether `m1nd` can answer or narrow the task directly.
+- Prefer the cheapest `m1nd` surface that preserves truth:
+  - exact text -> `search`
+  - path pattern -> `glob`
+  - known purpose, unknown location -> `seek`
+  - topic, subsystem, or connected neighborhood -> `activate`
+  - unfamiliar repo orientation -> `audit`
+  - stacktrace or runtime error text -> `trace`
+- For docs/specs/knowledge:
+  - authored as `L1GHT` -> `ingest` with `adapter: "light"`
+  - ordinary docs/wiki/PDF/office docs -> `ingest` with `adapter: "universal"` or `adapter: "auto"`
+- Before risky edits or change reviews, pass through `impact`, `validate_plan`, and usually `surgical_context_v2`.
+- Keep `agent_id` stable across one investigation unless intentionally splitting roles.
+
+## Skip Conditions
+
+Skip the `m1nd` first pass only when:
+
+- the user already gave the exact file and exact lines
+- the question is compiler, test, or runtime truth rather than structure
+- the task is a trivial local file action with no structural uncertainty
+
+## Fallback
+
+If `m1nd` does not answer enough, then fall back to shell search, direct file reads, compiler output, tests, logs, and debugger data.
+
+For local m1nd repo work, prefer the cheap trust selftest path before a full smoke:
+
+```bash
+python3 scripts/mcp_agent_smoke.py --repo . --handshake-only --json
+```
+
+When the live MCP surface exposes `trust_selftest`, call that tool first:
+
+```json
+{"agent_id":"codex-m1nd"}
+```
+
+Treat its `verdict` as the session routing decision before relying on
+retrieval. If the verdict is not `full_trust`, follow the embedded
+`recovery_playbook` or call `recovery_playbook` with the same evidence before
+guessing the next move. The selftest is diagnostic-only: no ingest, repair,
+host refresh, graph mutation, or retrieval probe happens automatically.
+
+If `trust_selftest` is not exposed but `session_handshake` is, call the cheaper
+sub-check:
+
+```json
+{"agent_id":"codex-m1nd"}
+```
+
+Treat its `trust_mode` as the session routing decision before relying on
+retrieval. If the mode is not `full_trust`, call `recovery_playbook` before
+guessing the next move. The playbook returns ordered recovery steps and a
+binding fingerprint without ingesting, repairing, or probing automatically.
+
+Use `--handshake-probe` only when retrieval trust itself matters. The plain
+selftest/handshake path should stay cheap: no ingest, no repair, and no
+retrieval probe by default. The repo-local smoke harness calls `trust_selftest`
+and `session_handshake` when available and falls back to its built-in handshake
+for older binaries.
+
+If the host exposes `health` but not `trust_selftest`, `session_handshake`, or
+`recovery_playbook`, read `health.tool_surface_contract` and
+`health.host_binding_alignment`.
+That is enough to classify the binding as partial/degraded and switch to local
+smokes or direct file truth until the host refreshes its tool surface.
+
+If `m1nd` is visible but the host tool surface is missing recovery tools such as
+`ingest`, treat it as `degraded_host_tool_surface`, not as a normal graph
+failure. Use whatever m1nd can still provide for orientation, but verify final
+truth against local files until the MCP binding is refreshed. If
+`recovery_playbook` is available, call it with the tool surface:
+
+```json
+{"agent_id":"codex-m1nd","observed_tool":"tools/list","observed_proof_state":"blocked","observed_tool_count":3,"available_tools":["seek","audit","doctor"],"missing_tools":["ingest"]}
+```
+
+If an `ingest` call appears to succeed but a follow-up retrieval call such as
+`seek`, `search`, or `activate` returns `blocked`, zero candidates, or an empty
+graph unexpectedly, do not assume the codebase is unindexed. Treat it as a
+possible host-binding/session-continuity problem. If `recovery_playbook` is
+available, use `recovery.arguments` from the retrieval response when present.
+If the response does not include a recovery payload, call `recovery_playbook`
+with the suspicious output first. Let the playbook decide when to call
+`doctor`:
+
+```json
+{"agent_id":"codex-m1nd","observed_tool":"seek","observed_proof_state":"blocked","observed_candidates":0}
+```
+
+If the repo has a local m1nd checkout, verify the real runtime with its stdio
+and HTTP smoke harness before deciding:
+
+```bash
+python3 scripts/mcp_agent_smoke.py --repo . --json
+python3 scripts/mcp_agent_smoke.py --repo . --transport http --json
+```
+
+## Deep Manual
+
+If the task needs detailed routing, `L1GHT` semantics, document-lane choice, multi-agent coordination, or refresh procedures, consult:
+
+- the companion `m1nd-operator` skill installed with this pack, usually at
+  `m1nd-operator/SKILL.md` in the same skills root.

package/skills/m1nd-operator/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: m1nd-operator
+description: Use when the user mentions m1nd or when repo investigation, search, review, docs/spec work, or risky change prep should go through m1nd first before grep, glob, or manual file reads. Covers m1nd-first routing, L1GHT and universal document ingestion, risky edit preparation, document-to-code binding, multi-agent coordination, trails/continuity, daemon alerts, and refreshing the live m1nd tool surface from the local m1nd-mcp binary.
+---
+
+# m1nd Operator
+
+This is the deep execution manual that complements the short `m1nd-first` doctrine.
+
+Use this skill when `m1nd` should be the first layer of truth for the task.
+
+`m1nd` is strongest when structure, connected context, blast radius, continuity, docs/code bindings, or multi-agent coordination are the bottleneck. It is not the replacement for `rg`, the compiler, runtime logs, or the test runner.
+
+## Default Stance
+
+Default to `m1nd` before grep, glob, or manual file reads.
+
+The first question is not "which shell command should I run?" It is "can `m1nd` answer or narrow this directly from graph structure, connected context, docs, or cross-domain bindings?"
+
+Only skip the `m1nd` first pass when:
+
+- the user already gave the exact file and exact lines
+- the question is pure compiler/test/runtime truth
+- the task is a trivial local file action with no search or structural uncertainty
+
+## Core Rules
+
+- Prefer the live MCP surface over stale prose. If tool names, counts, or parameters matter, run the bundled helper from this skill directory: `python3 scripts/probe_m1nd.py tools`.
+- Keep `agent_id` stable within one investigation. Change it only when intentionally starting another role or another concurrent investigation.
+- Ingest first. Re-ingest after code changes, or use incremental ingest for code repos when appropriate.
+- If the live MCP surface exposes `trust_selftest`, call it first and route by
+  `verdict` before relying on retrieval. `full_trust` means proceed with
+  m1nd-first; `needs_ingest` means ingest the intended repo; `orientation_only`
+  or `degraded_host_tool_surface` means use m1nd only for orientation and
+  verify final truth with local files until the binding is refreshed;
+  `stale_binding_suspected` means compare binding fingerprints and follow the
+  recovery playbook before trusting retrieval.
+- If `trust_selftest` is not exposed but `session_handshake` is, call the
+  handshake and route by `trust_mode` as the cheaper sub-check.
+- If the selftest verdict or handshake trust mode is not `full_trust`, or
+  retrieval returns `blocked`/zero candidates unexpectedly, call
+  `recovery_playbook` before inventing the next step. Use its ordered steps and
+  `binding_fingerprint` to compare host, stdio, HTTP, runtime root, graph paths,
+  generation counters, and ingest roots.
+- If the host exposes `health` but not `trust_selftest`, `session_handshake`, or
+  `recovery_playbook`, read `health.tool_surface_contract` and
+  `health.host_binding_alignment`. Treat missing required host-visible tools as
+  `degraded_host_tool_surface`, then verify with repo-local smokes or direct
+  files until the host refreshes its binding.
+- After ingest, sanity-check that retrieval is seeing the same active graph. If
+  `seek`, `search`, or `activate` returns `blocked`, zero candidates, or an
+  unexpectedly empty graph immediately after a successful ingest, suspect
+  host-binding/session split-brain before blaming the repo or the m1nd core.
+  If the response includes `recovery.arguments`, pass those arguments directly
+  to `recovery_playbook`. Otherwise, call `recovery_playbook` with
+  `observed_tool`, `observed_proof_state`, and `observed_candidates` from the
+  suspicious response before falling back. Let the playbook decide when to call
+  `doctor`.
+- If the host tool surface exposes m1nd but is missing recovery tools such as
+  `ingest`, classify the session as `degraded_host_tool_surface`. If `doctor`
+  is available, call it with `observed_tool="tools/list"`,
+  `observed_tool_count`, `available_tools`, and `missing_tools`. Until the MCP
+  binding is refreshed, use m1nd only as orientation and verify final truth with
+  direct repo files.
+- Make `m1nd` the first investigative step before shell search:
+  - exact text need -> try `search` before `rg`
+  - path pattern need -> try `glob` before filesystem globbing
+  - implementation-by-purpose need -> try `seek`
+  - subsystem/topic/connected neighborhood need -> try `activate`
+- Treat `proof_state`, `next_suggested_tool`, `next_suggested_target`, and `next_step_hint` as workflow control signals, not decorative fields.
+- Use the cheapest surface that preserves structural truth:
+  - exact text -> `search`
+  - path pattern -> `glob`
+  - known file -> `view`
+  - known purpose, unknown location -> `seek`
+  - topic/subsystem/neighborhood -> `activate`
+- For docs/specs/knowledge, decide the lane early:
+  - authored as graph-native semantic markdown -> `ingest` with `adapter: "light"`
+  - ordinary markdown/wiki/HTML/PDF/office docs -> `ingest` with `adapter: "universal"` or `adapter: "auto"`
+- Before risky edits, route through `impact`, `validate_plan`, and usually `surgical_context_v2`.
+- In Codex, prefer `m1nd` for analysis, planning, and context. If the task requires local file edits under Codex's editing rules, use `apply_patch` for the final file mutation unless there is a specific reason to use `m1nd`'s write surfaces.
+
+## Fast Routing
+
+- Unfamiliar repo or need a one-call orientation: use `audit`, then `batch_view`, `coverage_session`, or `cross_verify` as needed.
+- Need a subsystem map: use `activate`.
+- Need code by intent: use `seek`.
+- Need why A connects to B: use `why`.
+- Smells like missing validation, abstraction, cleanup, or lock: use `missing`.
+- Have a stacktrace or runtime error text: use `trace`.
+- Need blast radius before editing: use `impact`.
+- Need co-change follow-through after editing: use `predict`.
+- Need plan completeness and missing tests before implementation or review: use `validate_plan`.
+- Need graph-native specs, design notes, or KB docs authored in `L1GHT`: ingest with `adapter: "light"` and usually `mode: "merge"`.
+- Need regular spec/wiki/PDF/doc alignment with code: ingest with `adapter: "universal"` or `auto`, then use `document_resolve`, `document_bindings`, and `document_drift`.
+- Need stateful navigation instead of stateless retrieval: use `perspective_*`.
+- Need session continuity or handoff: use `trail_save`, `trail_list`, `trail_resume`, `trail_merge`, and sometimes `boot_memory`.
+- Need background structural monitoring: use `daemon_start`, `daemon_status`, `daemon_tick`, `alerts_list`, and `alerts_ack`.
+
+## Read These References
+
+- `references/routing-playbooks.md`
+  - Use for end-to-end workflows by task type: onboarding, bug triage, risky change prep, spec-to-code work, multi-agent sessions, and long-lived monitoring.
+- `references/tool-families.md`
+  - Use for the complete capability map grouped by family, including the less obvious tools (`antibody_*`, `runtime_overlay`, `ghost_edges`, `flow_simulate`, `layers`, `refactor_plan`, etc.).
+- `references/runtime-and-refresh.md`
+  - Use for local installation facts, current live-surface notes, the docs-vs-runtime count discrepancy, refresh procedure, and the helper script usage.
+- `references/l1ght-and-docs.md`
+  - Use for the `L1GHT` mental model, marker vocabulary, header fields, `light` vs `universal`, and mixed code+docs graph workflows.
+
+## Local Helper
+
+Use the bundled probe script from this skill directory whenever the live runtime matters more than remembered docs.
+
+```bash
+python3 scripts/probe_m1nd.py tools
+python3 scripts/probe_m1nd.py call health '{"agent_id":"codex-m1nd"}'
+python3 scripts/probe_m1nd.py call trust_selftest '{"agent_id":"codex-m1nd"}'
+python3 scripts/probe_m1nd.py call recovery_playbook '{"agent_id":"codex-m1nd","observed_tool":"seek","observed_proof_state":"blocked","observed_candidates":0}'
+python3 scripts/probe_m1nd.py call help '{"agent_id":"codex-m1nd","tool_name":"validate_plan"}'
+python3 scripts/probe_m1nd.py run '[{"name":"ingest","arguments":{"agent_id":"codex-m1nd","path":"/path/to/repo"}},{"name":"seek","arguments":{"agent_id":"codex-m1nd","query":"where retry backoff is decided","top_k":5}}]'
+```
+
+For the m1nd repo itself, prefer the repo-local agent smoke harness when you
+need to distinguish a real runtime problem from a host-provided MCP binding
+problem:
+
+```bash
+python3 scripts/mcp_agent_smoke.py --repo . --handshake-only --json
+python3 scripts/mcp_agent_smoke.py --repo . --handshake-only --handshake-probe --json
+python3 scripts/mcp_agent_smoke.py --repo . --json
+python3 scripts/mcp_agent_smoke.py --repo . --transport http --json
+```
+
+Use `trust_selftest` as the cheap default when exposed. The current binary also
+exposes the sub-check as `session_handshake`; the harness calls both when
+available and falls back for older binaries. The default path must stay
+diagnostic-only: no ingest, no repair, and no retrieval probe by default.
+`recovery_playbook` is the in-band next-step surface when the selftest,
+handshake, or retrieval looks suspicious. Add `--handshake-probe` only when the
+task depends on retrieval trust.
+
+That harness proves the minimum trust loop over real Content-Length framed
+stdio and the HTTP tool API:
+
+```text
+initialize -> tools/list -> trust_selftest -> session_handshake -> recovery_playbook when needed -> ingest -> seek -> help -> doctor
+```
+
+What the helper is for:
+
+- confirming the local binary still responds
+- listing the live tool surface
+- detecting `degraded_host_tool_surface` when required tools such as `ingest`,
+  `seek`, `help`, `recovery_playbook`, or `doctor` are missing
+- checking a tool's real response shape without relying on stale wiki prose
+- catching graph/session continuity failures before falling back to broad shell
+  search
+
+## Working Posture
+
+- Use `m1nd` when the question is about relationships, not just strings.
+- Use `m1nd` first even when the answer might be textual, because `search`, `seek`, and `activate` can often narrow the surface before any shell reads.
+- Use `m1nd` before big changes when hidden neighbors or missing tests could bite later.
+- Use `m1nd` for continuity when the same investigation spans agents or sessions.
+- Fall back to `rg`, direct file reads, compiler output, and runtime logs when execution truth is the real question.

package/skills/m1nd-operator/references/l1ght-and-docs.md

@@ -0,0 +1,164 @@
+# L1GHT And Document Lanes
+
+This file captures the document side of `m1nd`, especially the distinction between the graph-native `L1GHT` lane and the more general `universal` document lane.
+
+## What L1GHT Is
+
+`L1GHT` is a graph-native semantic markdown protocol.
+
+Use it when the document is meant to be an active part of the graph, not just a file to canonicalize and later bind. In the repo's public description, `light` is "structured markdown with typed YAML frontmatter and inline semantic markers" that turns specs, design decisions, and knowledge bases into first-class graph nodes with typed edges.
+
+Practical meaning:
+
+- code and structured docs can live in the same graph
+- `activate`, `seek`, and other structural tools can surface both implementation and semantic spec nodes together
+- this is the right lane when the doc itself is authored as machine-legible graph material
+
+## When To Use `light` vs `universal`
+
+Use `adapter: "light"` when:
+
+- the markdown is intentionally authored in the `L1GHT` protocol
+- the document should become graph-native semantic structure directly
+- you want typed nodes and typed edges extracted from headers, sections, and inline semantic markers
+
+Use `adapter: "universal"` or `adapter: "auto"` when:
+
+- the source is ordinary markdown, wiki, HTML, PDF, office docs, or other non-L1GHT artifacts
+- you want canonical local artifacts like `canonical.md`, `canonical.json`, and `claims.json`
+- you want `document_resolve`, `document_bindings`, and `document_drift` on docs that were not authored as L1GHT
+
+Short rule:
+
+- authored graph-native spec -> `light`
+- arbitrary doc you still want inside the graph -> `universal`
+
+## What The Local Adapter Actually Recognizes
+
+From the current `m1nd-ingest/src/l1ght_adapter.rs` implementation:
+
+- it accepts `.md` and `.markdown`
+- it positively recognizes `Protocol: L1GHT/`
+- it also heuristically recognizes L1GHT-like files when enough semantic markers exist
+
+The current heuristic marker set includes:
+
+- `[⍂ entity: ...]`
+- `[⍐ state: ...]`
+- `[⍌ event: ...]`
+- `[𝔻 confidence: ...]`
+- `[𝔻 ambiguity: ...]`
+- `[𝔻 evidence: ...]`
+- `[⟁ depends_on: ...]`
+- `[⟁ binds_to: ...]`
+- `[⟁ tests: ...]`
+- `[RED blocker: ...]`
+- `[AMBER warning: ...]`
+
+## Header Fields Understood By The Current Adapter
+
+The adapter parses these header-level fields today:
+
+- `Protocol:`
+- `Node:`
+- `State:`
+- `Color:`
+- `Glyph:`
+- `Completeness:`
+- `Proof:`
+- `Depends on:`
+- `Next:`
+
+These become graph metadata nodes and/or typed edges.
+
+Examples of edge semantics from the adapter:
+
+- `depends_on` from header dependencies
+- `next_binding` from `Next:`
+- `defines_protocol`
+- `has_state`
+- `has_glyph`
+- `has_color`
+- generic `has_metadata`
+
+## Structural Materialization In The Graph
+
+The current adapter creates graph-native structure from the markdown:
+
+- the file becomes a canonical file node
+- `##` headings become section nodes
+- header metadata becomes concept/reference nodes
+- inline semantic markers become typed concept or process nodes
+
+Current inline relation mapping includes:
+
+- `[⍂ entity: ...]` -> `declares_entity`
+- `[⍐ state: ...]` -> `declares_state`
+- `[⍌ event: ...]` -> `declares_event`
+- `[⟁ depends_on: ...]` -> `depends_on`
+- `[⟁ binds_to: ...]` -> `binds_to`
+- `[⟁ tests: ...]` -> `declares_test`
+- `[RED blocker: ...]` -> `declares_blocker`
+- `[AMBER warning: ...]` -> `declares_warning`
+- everything else falls back to `declares_metadata`
+
+This means `L1GHT` is not "markdown plus tags"; it is a semantic ingest format that turns authored knowledge into graph structure.
+
+## Small Example
+
+Illustrative shape from the docs:
+
+```text
+---
+Protocol: L1GHT/1.0
+Node:     AuthService
+State:    production
+Depends on:
+- JWTService
+- SessionStore
+---
+
+## Token Validation
+
+The [⍂ entity: TokenValidator] runs HMAC-SHA256 checks.
+[⟁ depends_on: RedisSessionStore]
+[RED blocker: Connection pool not yet tuned for peak load]
+```
+
+Typical mixed-graph use:
+
+```json
+{"method":"tools/call","params":{"name":"ingest","arguments":{
+  "agent_id":"dev",
+  "path":"./src",
+  "adapter":"code",
+  "mode":"replace"
+}}}
+
+{"method":"tools/call","params":{"name":"ingest","arguments":{
+  "agent_id":"dev",
+  "path":"./docs/specs",
+  "adapter":"light",
+  "mode":"merge"
+}}}
+```
+
+After that, graph queries can land in code or L1GHT nodes from one search space.
+
+## How I Should Use This As An Agent
+
+When a task involves docs, specs, or conceptual design artifacts:
+
+1. Ask whether the source is authored as `L1GHT` or is just a regular document.
+2. If it is `L1GHT`, prefer `ingest` with `adapter: "light"` and usually `mode: "merge"`.
+3. If it is regular documentation, prefer `adapter: "universal"` or `auto`.
+4. Query the combined graph with `search`, `seek`, `activate`, `impact`, or `validate_plan` before falling back to manual document reading.
+
+## Important Distinction To Remember
+
+`L1GHT` and `document_*` are related but not identical concerns.
+
+- `L1GHT` is an authored semantic document protocol that becomes graph-native directly.
+- `document_*` tools are most relevant for universal-document handling, canonical artifacts, and doc-to-code binding/drift workflows.
+
+So if the user says "spec" or "wiki", do not assume `universal` immediately. First check whether the material is already authored in `L1GHT`.