@modootoday/pmcp 0.5.1 → 0.7.0

package/README.md

@@ -70,6 +70,49 @@ Paths resolve against the file's directory. Keys are `roots`, `scopes`,
 the same meaning; an unknown key is an error. A flag replaces the file's list
 of its kind. `--config <file>` names another file and `--no-config` ignores it.
 
+## Native files for each agent tool
+
+`pmcp project` writes what Claude Code, Codex, Gemini CLI, Grok Build and
+Antigravity read natively, from cross-tool sources under `.agents/`
+(`skills/<name>/SKILL.md`, `agents/<name>/agent.md`, `rules/*.md`) and the rest
+of `pmcp.toml`:
+
+```toml
+[targets]
+tools = ["claude", "codex", "gemini", "grok", "antigravity"]
+
+[skills.deploy]
+invocation = "user"          # the person starts it; the model is not offered it
+
+[agents.reviewer.claude]
+tools = "Read, Grep"         # fields one tool reads stay out of agent.md
+
+[rules.packages]
+file = ".agent/rules/PACKAGE.RULE.md"   # each package's path-scoped rule
+strip = ["apps"]                        # dropped from derived link names
+
+[mcp.skills]
+command = "node"
+args = ["${PROJECT_ROOT}/node_modules/@modootoday/pmcp/dist/cli.js", "serve"]
+```
+
+```sh
+pmcp project              # write
+pmcp project --check      # exit 2 on drift, stale or undeclared outputs
+pmcp project add <name>   # copy a catalog skill or agent into .agents/
+pmcp project remove <name>
+pmcp doctor               # ask each installed tool what it loads
+```
+
+Rules go to `.claude/rules/<dir>/`, never the top level, because Grok Build
+loads top-level `.claude/rules/*.md` in every session regardless of `paths:`.
+A server that names `${PROJECT_ROOT}` is launched through `sh`, which finds
+`pmcp.toml` at spawn time, so the generated files hold no machine's path.
+`pmcp.lock` records what was written; a file pmcp did not write is never
+overwritten. `doctor` calls no model: it reads `claude mcp list`,
+`codex mcp list`, `gemini skills list`, `gemini mcp list` and
+`grok inspect --json`, and skips a tool that is not installed.
+
 ## Package skills
 
 Skills are discovered by filename, including `skills/`, `.agents/skills/`,
@@ -117,11 +160,18 @@ export default { fetch: (request: Request) => skills.fetch(request) };
 
 Put Origin and Host validation in front of it when it is mounted bare.
 
+Pass `semantic: { cacheDir, localOnly: true }` to rank by meaning: the handler encodes
+the catalog at start with `@huggingface/transformers` and the multilingual model, so an
+intent in one language finds a description in another. Requests rank lexically until
+`ready()` settles, and stay lexical when the encoder cannot load (`onError` says why).
+
 ## Runtime and licence
 
-Node.js 22 or later, or Bun 1.3 or later. Default ranking is lexical. The optional
-`index` command requires a separately installed encoder; it is not part of the
-default installation.
+Node.js 22 or later, or Bun 1.3 or later. Default ranking is lexical. Semantic
+ranking (the `index` command, or the HTTP handler's `semantic` option) needs
+`@huggingface/transformers` installed separately; it is not part of the default
+installation. The default encoder is `Xenova/multilingual-e5-small` (MIT, about
+130 MB), so vectors indexed with the earlier English-only default are re-encoded.
 
 Elastic License 2.0. See `LICENSE` and `NOTICE` for terms and dependency notices.
 Documentation: <https://pmcp.build>.