@sporhq/spor 0.1.1 → 0.2.1

package/LICENSE

@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2026 Anthony Allen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Anthony Allen
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,13 @@
+Spor
+Copyright 2026 Anthony Allen
+
+This product is developed as part of the Spor project (https://sporhq.io).
+
+Licensed under the Apache License, Version 2.0 (see the "LICENSE" file in this
+distribution). Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+"Spor" and "sporhq" are trademarks of Anthony Allen. The Apache License grants
+no permission to use these marks; their use is governed separately by the
+trademark policy in the "TRADEMARKS.md" file.

package/README.md

@@ -20,7 +20,7 @@ dispatcher hosts call):
 npm install -g @sporhq/spor
 ```
 
-Requires Node 18+ and nothing else — the client is zero-dependency. To run
+Requires Node 20+ and nothing else — the client is zero-dependency. To run
 from a checkout instead (e.g. to hack on it), clone the repo and `npm link`
 from its root; that symlinks the same two commands onto your PATH.
 
@@ -36,15 +36,32 @@ time you're unsure whether Spor is active or which graph you're on. (Without
 the `spor` CLI on your PATH the equivalent is
 `mkdir -p ~/.spor/nodes && git -C ~/.spor init && printf 'journal/\n' > ~/.spor/.gitignore`.)
 
-Then install for your agent. In Claude Code:
+Then install for your agent. One verb wires up any supported host — it
+resolves the adapter manifest to this checkout and drops it into the host's
+config:
+
+```bash
+spor install claude     # Claude Code (via its plugin CLI — no marketplace browsing)
+spor install codex      # also: gemini, cursor, copilot, opencode
+spor install            # no host => list the hosts detected on this machine
+```
+
+`--scope user` (default) installs for you; `--scope repo` writes a committable
+per-repo config. `--all` installs every detected host, `--print` is a dry run,
+and `--server <url> --token <tok>` also points the client at a team graph in
+the same step. Re-running is idempotent — it refreshes the path and never
+duplicates your other hooks.
+
+In Claude Code you can still install from the marketplace by hand if you
+prefer:
 
 ```
 /plugin marketplace add sporhq/spor
 /plugin install spor@spor
 ```
 
-For every other host — Codex CLI, Gemini CLI, Cursor, Copilot CLI, OpenCode,
-and an `AGENTS.md` fallback for hosts with no hook support — see
+For the per-host event mapping, fidelity notes, distiller backend, and the
+`AGENTS.md` fallback for hosts with no hook support, see
 [adapters/](adapters/).
 
 To start with a populated graph, point the bundled `spor-backfill` agent at
@@ -202,3 +219,17 @@ verifiable rather than asserted:
   write semantics, identity and auth, and client configuration.
 - [adapters/](adapters/) — supported coding agents and how install works on
   each, including the `AGENTS.md` floor for hosts without hooks.
+
+## License
+
+Spor (this client) is licensed under the [Apache License 2.0](LICENSE) — a
+permissive license with an explicit patent grant. See [NOTICE](NOTICE) for
+attribution.
+
+"Spor" and "sporhq" are trademarks of the project; the Apache License grants no
+rights to the marks. Their use is governed by the [Trademark Policy](TRADEMARKS.md)
+— in short, build "an adapter **for** Spor," not a product **named** Spor.
+
+Contributions are welcome under inbound = outbound (Apache-2.0); see
+[CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and the
+[Code of Conduct](CODE_OF_CONDUCT.md).

package/TRADEMARKS.md

@@ -0,0 +1,102 @@
+# Trademark Policy
+
+This document, the "Policy," describes how you may use the trademarks of the
+Spor project (the "Project"). Spor's software is available under a free and
+open source license — the [Apache License 2.0](LICENSE) — but that copyright
+license grants **no** right, express or implied, to use the Project's
+trademarks (see Section 6 of the Apache License). This Policy is where we
+describe the use we permit.
+
+The role of a trademark is to assure people about the source and quality of
+the thing carrying it. Because the open source license lets you modify the
+software freely, we cannot guarantee that a modified version distributed under
+our name still behaves the way users expect. This Policy describes how you may
+use our marks to accurately describe your relationship to Spor without creating
+that confusion.
+
+## Marks covered
+
+This Policy covers the following word marks (the "Marks"):
+
+| Mark        | Common descriptive name             |
+| ----------- | ----------------------------------- |
+| Spor        | knowledge-graph context software    |
+| spor        | knowledge-graph context software    |
+| sporhq      | knowledge-graph context software    |
+| sporhq.io   | knowledge-graph context software    |
+
+It also covers the Spor logo and visual identity ("trade dress").
+
+**Registration is not required.** Trademark rights arise from use in commerce.
+Some or all of the Marks may be unregistered; this Policy and our rights apply
+whether or not a Mark is registered. Until a registration issues for a Mark, it
+is identified with a "™" symbol; a registered Mark would use "®".
+
+## Universal considerations
+
+Whenever you use a Mark you must do so in a way that does not mislead anyone,
+directly or by omission, about what they are getting and from whom. In
+particular:
+
+- You may not use a Mark in a way that suggests your product, service, or site
+  is produced, endorsed, or sponsored by the Project when it is not.
+- You may not use or register a Mark, in whole or in part, as part of your own
+  trademark, product name, service name, company name, domain name, or social
+  account.
+- You may not use a confusingly similar variant — a phonetic equivalent,
+  translation, misspelling, or abbreviation — for a similar or competing
+  product or service.
+- You may not use a Mark in connection with software that you are distributing
+  out of compliance with the Apache License.
+
+Any goodwill from your use of the Marks inures solely to the Project.
+
+## Uses that do not need permission
+
+- **Redistributing the unmodified software.** If you redistribute an official,
+  unmodified release of Spor, you may keep the Marks and notices it ships with.
+- **Describing compatibility or a relationship truthfully.** Use a Mark after a
+  verb or preposition that describes the relationship — for example
+  "an adapter **for** Spor", "works **with** Spor", "compatible **with** Spor",
+  "built **on** Spor". Do not use a Mark as the name of your own thing
+  ("Spor Pro", "SporCloud", "Spor for X" as a product name).
+- **Nominative reference.** You may use a Mark as much as is reasonably
+  necessary to identify Spor in articles, talks, documentation, and tutorials,
+  provided you do not imply endorsement.
+- **Functional, non-trademark use.** Using the word `spor` functionally inside
+  software — as a command name, package name on a registry where it identifies
+  this Project's software, file or directory name, config key, or environment
+  variable (e.g. `spor install`, `SPOR_SERVER`, `@sporhq/spor`) — is not a
+  trademark use and is unrestricted.
+
+## Uses that need our permission
+
+- Using a Mark on a **modified** build of Spor distributed to others (it may no
+  longer behave as users expect under our name).
+- Using a Mark, or a confusingly similar term, as part of a **product, service,
+  company, or domain name**, including for a hosted/SaaS offering.
+- Using the Spor **logo** other than in unmodified redistribution or clearly
+  nominative reference.
+- Using a Mark on **merchandise** or in advertising in a way that implies
+  endorsement.
+
+If you want to do any of these, ask first (see below).
+
+## Proper use
+
+Distinguish a Mark from surrounding text (initial capital — "Spor", not
+"spor", except in the functional/technical uses above), use it as an adjective
+("a Spor briefing", not "a Spor" / "to Spor something"), do not pluralize or
+hyphenate it, and do not translate it.
+
+## Questions and reports
+
+To ask about a use not covered here, request permission, or report misuse,
+open an issue at <https://github.com/sporhq/spor/issues> or contact us via
+<https://sporhq.io>.
+
+---
+
+These guidelines are adapted from the
+[Model Trademark Guidelines](http://www.modeltrademarkguidelines.org), used
+under a Creative Commons Attribution 3.0 Unported license.

package/adapters/README.md

@@ -1,5 +1,13 @@
 # Host adapters
 
+> **Installing:** `spor install <host>` (e.g. `spor install codex`) automates
+> the per-host recipe below — it resolves the `__SPOR_ROOT__` placeholder to
+> your checkout and merges the manifest into the host's config (idempotently;
+> `--scope user|repo`, `--all`, `--print`). The manual steps in each adapter's
+> README remain valid for hand-installs or when you want to see exactly what
+> lands where. Claude Code installs via its own plugin CLI (`spor install
+> claude`), not a file drop.
+
 The Spor client is a portable core behind per-host adapters
 (dec-cc-portable-core-adapters):
 

package/bin/spor.js

@@ -18,6 +18,7 @@
 // never dumps a stack trace at the user.
 
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
@@ -32,6 +33,9 @@ Usage: spor <verb> [args]
 
 Getting started
   init                 create the local graph home (nodes/, git, .gitignore)
+  install [host...]    wire spor into an agent: claude codex gemini opencode
+                       copilot cursor (no host => list detected). --scope
+                       user|repo, --all, --print, --server/--token to configure
   status               resolved mode, graph, project, identity, health
   join <url> <token>   point the client at a graph (writes user config)
   migrate <url>        push the local graph to a remote you own (solo-remote)
@@ -345,6 +349,24 @@ async function cmdAdd(cfg, args) {
   return 0;
 }
 
+// Persist server/token into the USER config (never a committable repo config).
+// Shared by 'join' and the 'install --server/--token' configure step. Only the
+// keys given are touched, so a token-only update keeps the existing server.
+function writeServerToken(home, server, token) {
+  const cfgFile = path.join(home, "config.json");
+  let data = {};
+  try {
+    data = JSON.parse(fs.readFileSync(cfgFile, "utf8")) || {};
+  } catch {
+    /* absent or malformed — start fresh */
+  }
+  if (server) data.server = server.replace(/\/+$/, "");
+  if (token) data.token = token;
+  fs.mkdirSync(home, { recursive: true });
+  fs.writeFileSync(cfgFile, JSON.stringify(data, null, 2) + "\n");
+  return cfgFile;
+}
+
 // --- spor join / login --------------------------------------------------
 // Write server+token to USER config (never a committable repo config), then
 // confirm immediately — the upgrade research found no one-step way to point a
@@ -357,21 +379,11 @@ async function cmdJoin(cfg, args) {
     err("usage: spor join <server-url> <token>");
     return 1;
   }
-  const home = cfg.graphHome();
-  const cfgFile = path.join(home, "config.json");
-  let data = {};
-  try {
-    data = JSON.parse(fs.readFileSync(cfgFile, "utf8")) || {};
-  } catch {
-    /* absent or malformed — start fresh */
-  }
-  data.server = server.replace(/\/+$/, "");
-  if (token) data.token = token;
+  let cfgFile;
   try {
-    fs.mkdirSync(home, { recursive: true });
-    fs.writeFileSync(cfgFile, JSON.stringify(data, null, 2) + "\n");
+    cfgFile = writeServerToken(cfg.graphHome(), server, token);
   } catch (e) {
-    err(`could not write ${cfgFile}: ${e.message}`);
+    err(`could not write config: ${e.message}`);
     return 1;
   }
   out(`wrote server${token ? " + token" : ""} to ${cfgFile}`);
@@ -640,6 +652,259 @@ function cmdLink(args) {
   return 0;
 }
 
+// --- spor install / setup: wire spor into a host agent ---------------------
+// dec-cc-portable-core-adapters ships a manifest per host under adapters/<host>/
+// with a __SPOR_ROOT__ placeholder; installing one resolves the placeholder to
+// THIS checkout and drops/merges the manifest into the host's config location.
+// Until now this was a manual sed/ln recipe in each adapter README — this verb
+// is its automation. Claude Code is special: it has no flat hook file, so we
+// shell out to its plugin CLI (this repo IS the marketplace) rather than
+// hand-edit ~/.claude/settings.json, which the CLI owns.
+const HOSTS = {
+  claude: { kind: "claude", label: "Claude Code" },
+  codex: { kind: "hooks", label: "Codex CLI", src: ["adapters", "codex", "hooks.json"], user: [".codex", "hooks.json"], repo: [".codex", "hooks.json"] },
+  cursor: { kind: "hooks", label: "Cursor", src: ["adapters", "cursor", "hooks.json"], user: [".cursor", "hooks.json"], repo: [".cursor", "hooks.json"] },
+  copilot: { kind: "hooks", label: "GitHub Copilot CLI", src: ["adapters", "copilot", "spor.json"], user: [".copilot", "hooks", "spor.json"], repo: [".github", "hooks", "spor.json"] },
+  gemini: { kind: "hooks", label: "Gemini CLI", src: ["adapters", "gemini", "hooks", "hooks.json"], user: [".gemini", "settings.json"], repo: [".gemini", "settings.json"] },
+  opencode: { kind: "plugin", label: "OpenCode", src: ["adapters", "opencode", "spor.js"], user: [".config", "opencode", "plugins", "spor.js"], repo: [".opencode", "plugins", "spor.js"] },
+};
+
+// The config dir whose presence means a host is set up on this machine.
+const HOST_PROBE = {
+  codex: [".codex"],
+  cursor: [".cursor"],
+  copilot: [".copilot"],
+  gemini: [".gemini"],
+  opencode: [".config", "opencode"],
+  claude: [".claude"],
+};
+
+// $HOME first so tests (and conventional overrides) win; os.homedir() is the
+// cross-platform fallback (USERPROFILE on Windows).
+function homeDir() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+// Options that consume the following token, so positional parsing can skip it.
+const INSTALL_VALUE_OPTS = new Set(["scope", "server", "token"]);
+function positionals(args) {
+  const pos = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      if (INSTALL_VALUE_OPTS.has(a.slice(2))) i++; // skip its value
+      continue;
+    }
+    pos.push(a);
+  }
+  return pos;
+}
+
+function deepReplace(v, from, to) {
+  if (typeof v === "string") return v.split(from).join(to);
+  if (Array.isArray(v)) return v.map((x) => deepReplace(x, from, to));
+  if (v && typeof v === "object") {
+    const o = {};
+    for (const k of Object.keys(v)) o[k] = deepReplace(v[k], from, to);
+    return o;
+  }
+  return v;
+}
+
+// Parse the manifest template as JSON, THEN substitute the root into string
+// values — so a Windows root with backslashes never has to survive JSON escaping.
+function renderManifest(srcSegs) {
+  const raw = fs.readFileSync(path.join(ROOT, ...srcSegs), "utf8");
+  return deepReplace(JSON.parse(raw), "__SPOR_ROOT__", ROOT);
+}
+
+function readJsonOr(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) || fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+// Merge our hooks.{event:[...]} into an existing host config without clobbering
+// the user's own hooks or top-level keys. Idempotent: prior spor entries (any
+// whose command mentions spor-hook) are dropped first, so re-install refreshes a
+// stale __SPOR_ROOT__ path instead of duplicating.
+function mergeHooks(existing, incoming) {
+  const merged = existing && typeof existing === "object" && !Array.isArray(existing) ? existing : {};
+  for (const k of Object.keys(incoming)) {
+    if (k === "hooks") continue;
+    if (merged[k] === undefined) merged[k] = incoming[k];
+  }
+  merged.hooks = merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {};
+  const inHooks = incoming.hooks || {};
+  for (const event of Object.keys(inHooks)) {
+    const prior = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
+    const kept = prior.filter((e) => !JSON.stringify(e).includes("spor-hook"));
+    merged.hooks[event] = kept.concat(inHooks[event]);
+  }
+  return merged;
+}
+
+function targetPath(spec, scope) {
+  return scope === "repo" ? path.join(repoRoot(), ...spec.repo) : path.join(homeDir(), ...spec.user);
+}
+
+function hasCmd(cmd) {
+  try {
+    return !spawnSync(cmd, ["--version"], { stdio: "ignore" }).error;
+  } catch {
+    return false;
+  }
+}
+
+function detectHosts() {
+  const home = homeDir();
+  const found = [];
+  for (const h of Object.keys(HOST_PROBE)) {
+    if (h === "claude") {
+      if (hasCmd("claude") || fs.existsSync(path.join(home, ".claude"))) found.push(h);
+      continue;
+    }
+    if (fs.existsSync(path.join(home, ...HOST_PROBE[h]))) found.push(h);
+  }
+  return found;
+}
+
+// Claude Code: shell out to its plugin CLI (the stable contract; settings.json
+// is CLI-owned). The marketplace IS this repo (.claude-plugin/marketplace.json,
+// name "spor"), so 'marketplace add <ROOT>' then 'install spor@spor'.
+function installClaude(scope, dryRun) {
+  const cliScope = scope === "repo" ? "project" : "user";
+  const addArgs = ["plugin", "marketplace", "add", ROOT];
+  const instArgs = ["plugin", "install", "spor@spor", "--scope", cliScope];
+  if (dryRun) {
+    out(`would run: claude ${addArgs.join(" ")}`);
+    out(`would run: claude ${instArgs.join(" ")}`);
+    return 0;
+  }
+  if (!hasCmd("claude")) {
+    err("claude CLI not on PATH — install Claude Code, then re-run 'spor install claude'.");
+    err(`meanwhile, load spor without a marketplace per session:  claude --plugin-dir ${ROOT}`);
+    return 1;
+  }
+  const add = spawnSync("claude", addArgs, { encoding: "utf8" });
+  if (add.status !== 0 && !/already|exists|known/i.test((add.stderr || "") + (add.stdout || ""))) {
+    err(`claude plugin marketplace add failed: ${(add.stderr || add.stdout || "").trim() || "unknown error"}`);
+    return 1;
+  }
+  const inst = spawnSync("claude", instArgs, { stdio: "inherit" });
+  if (inst.status !== 0) {
+    err(`claude plugin install failed (exit ${inst.status == null ? "?" : inst.status})`);
+    return 1;
+  }
+  out(`installed spor@spor into Claude Code (scope: ${cliScope}) — no marketplace browsing needed.`);
+  return 0;
+}
+
+// JSON-hook hosts (codex/cursor/copilot/gemini): render + merge into the target.
+function installHookHost(spec, scope, dryRun) {
+  const target = targetPath(spec, scope);
+  const merged = mergeHooks(readJsonOr(target, {}), renderManifest(spec.src));
+  if (dryRun) {
+    out(`would write ${target}:`);
+    out(JSON.stringify(merged, null, 2));
+    return 0;
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, JSON.stringify(merged, null, 2) + "\n");
+  out(`installed spor for ${spec.label} → ${target}  (scope: ${scope})`);
+  return 0;
+}
+
+// OpenCode has no command hooks — a JS plugin file is symlinked into place so it
+// resolves the core via the link; copy is the Windows/EPERM fallback.
+function installPluginHost(spec, scope, dryRun) {
+  const src = path.join(ROOT, ...spec.src);
+  const target = targetPath(spec, scope);
+  if (dryRun) {
+    out(`would link ${target} -> ${src}`);
+    return 0;
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  try {
+    fs.rmSync(target, { force: true });
+  } catch {
+    /* nothing there */
+  }
+  let how = "linked";
+  try {
+    fs.symlinkSync(src, target);
+  } catch {
+    fs.copyFileSync(src, target);
+    how = "copied";
+  }
+  out(`installed spor for ${spec.label} → ${target}  (${how}, scope: ${scope})`);
+  if (how === "copied") out(`  note: copied (no symlink here) — export SPOR_ROOT=${ROOT} so the plugin finds its core.`);
+  return 0;
+}
+
+async function cmdInstall(cfg, args) {
+  const dryRun = args.includes("--print") || args.includes("--dry-run");
+  let scope = optVal(args, "scope") || "user";
+  if (scope === "project") scope = "repo";
+  if (scope !== "user" && scope !== "repo") {
+    err(`invalid --scope '${scope}' — use 'user' or 'repo'`);
+    return 1;
+  }
+
+  const pos = positionals(args);
+  const bad = pos.find((a) => !HOSTS[a]);
+  if (bad) {
+    err(`unknown host '${bad}' — known: ${Object.keys(HOSTS).join(", ")}`);
+    return 1;
+  }
+  let hosts = pos.slice();
+  if (args.includes("--all")) hosts = detectHosts();
+
+  // The "configure" half: persist server/token to user config when given.
+  const server = optVal(args, "server");
+  const token = optVal(args, "token");
+  if ((server || token) && !dryRun) {
+    try {
+      const f = writeServerToken(cfg.graphHome(), server, token);
+      out(`wrote ${[server && "server", token && "token"].filter(Boolean).join(" + ")} to ${f}`);
+    } catch (e) {
+      err(`could not write config: ${e.message}`);
+    }
+  }
+
+  if (!hosts.length) {
+    // Discovery mode — show what is installable; touch nothing.
+    const found = detectHosts();
+    out("Usage: spor install <host>... [--scope user|repo] [--all] [--print]");
+    out(`Hosts: ${Object.keys(HOSTS).join(", ")}`);
+    out(found.length ? `Detected here: ${found.join(", ")}  (try: spor install ${found.join(" ")})` : "No host config dirs detected yet.");
+    out("Claude Code: 'spor install claude' wires the plugin via its CLI — no marketplace browsing.");
+    return 0;
+  }
+
+  let rc = 0;
+  for (const host of hosts) {
+    const spec = HOSTS[host];
+    let r;
+    if (spec.kind === "claude") r = installClaude(scope, dryRun);
+    else if (spec.kind === "plugin") r = installPluginHost(spec, scope, dryRun);
+    else r = installHookHost(spec, scope, dryRun);
+    if (r !== 0) rc = r;
+  }
+
+  if (!dryRun && hosts.some((h) => HOSTS[h].kind !== "claude")) {
+    out("");
+    out("next:");
+    if (cfg.mode() === "remote") out(`  remote mode is configured (${remote.base(cfg)}).`);
+    else out("  point at a graph:  spor join <server-url> <token>   (or export SPOR_SERVER/SPOR_TOKEN)");
+    out("  distiller backend (hosts without the claude CLI) + on-demand MCP access: see adapters/<host>/README.md");
+    out("  approve the hooks on first run if the host prompts.");
+  }
+  return rc;
+}
+
 function version() {
   try {
     return require(path.join(ROOT, "package.json")).version || "0.0.0";
@@ -668,6 +933,9 @@ async function main() {
       return 0;
     case "init":
       return cmdInit(cfg);
+    case "install":
+    case "setup":
+      return await cmdInstall(cfg, args);
     case "status":
       return await cmdStatus(cfg);
     case "whoami":

package/lib/remote.js

@@ -1,7 +1,7 @@
 "use strict";
 // remote.js — minimal zero-dependency REST client for the Spor server, used by
 // the bin/spor CLI in remote mode (dec-cc-spor-cli-universal-surface step 3).
-// `fetch` is a Node 18+ global (package.json engines), so no dependency.
+// `fetch` is a Node 20+ global (package.json engines), so no dependency.
 //
 // Fail-open parity with the hooks (dec-cc-fail-open-hooks): a transport error
 // (DNS, refused, timeout) resolves to { ok:false, transport:true } rather than

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Spor — a shared memory substrate for teams and agents. Decisions, their reasons, and the traces they leave. Knowledge-graph context compiler: session-start briefings, per-prompt digests, capture at discovery, end-of-session distillation, decision queue.",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "author": "Anthony Allen",
   "homepage": "https://sporhq.io",
   "repository": {
@@ -39,13 +39,15 @@
     "workers/",
     "API.md",
     "GRAPH.md",
-    "QUEUE.md"
+    "QUEUE.md",
+    "NOTICE",
+    "TRADEMARKS.md"
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
     "conformance": "node conformance/runner.js"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   }
 }