@jitera/connect 0.1.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "jitera",
+  "description": "Connect AI coding assistants to Jitera projects: project documentation, source, and shared project memory.",
+  "owner": {
+    "name": "Jitera"
+  },
+  "plugins": [
+    {
+      "name": "jitera-connect",
+      "source": "./",
+      "description": "Connect this workspace to a Jitera project: read documentation and source, and keep project memory up to date."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,33 @@
+{
+  "name": "jitera-connect",
+  "version": "0.1.1",
+  "description": "Connect this workspace to a Jitera project: read documentation and source, and keep project memory up to date.",
+  "author": {
+    "name": "Jitera"
+  },
+  "mcpServers": {
+    "jitera": {
+      "type": "http",
+      "url": "${user_config.jitera_mcp_url}",
+      "headers": {
+        "Authorization": "Bearer ${user_config.jitera_api_key}"
+      }
+    }
+  },
+  "userConfig": {
+    "jitera_api_key": {
+      "type": "string",
+      "title": "API key",
+      "description": "Create one in your project settings. Choose read + write access if you want the assistant to save memory and write specs.",
+      "sensitive": true,
+      "required": true
+    },
+    "jitera_mcp_url": {
+      "type": "string",
+      "title": "MCP endpoint",
+      "description": "Leave as-is for Jitera Cloud. Self-hosted and non-production deployments use a different host.",
+      "default": "https://gateway-proxy.jitera.app/gateway/boost/mcp",
+      "required": true
+    }
+  }
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "jitera-connect",
+  "version": "0.1.1",
+  "description": "Connect this workspace to a Jitera project: read documentation and source, and keep project memory up to date.",
+  "skills": "./skills/"
+}

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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 Jitera
+
+   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/README.md

@@ -0,0 +1,27 @@
+# how to install
+
+## claude code
+
+```
+/plugin marketplace add jitera-product/connect
+/plugin install jitera-connect
+```
+
+## codex
+
+```
+codex plugin marketplace add jitera-product/connect
+```
+
+## cursor
+
+```
+npx @jitera-product/connect
+```
+
+## pilot and staging environments
+
+```
+npx @jitera-product/connect --env=studio-stage
+npx @jitera-product/connect --env=studio-06
+```

package/bin/jitera-connect.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+
+import { cursor } from "../src/adapters/cursor.mjs";
+import { MalformedConfigError } from "../src/mcp-config.mjs";
+import { UnknownEnvironmentError, resolveApiBaseUrl, resolveMcpUrl } from "../src/environments.mjs";
+
+const ADAPTERS = [cursor];
+
+function parseArgs(argv) {
+  const args = { scope: "project" };
+  for (const arg of argv) {
+    if (arg.startsWith("--env=")) args.env = arg.slice("--env=".length);
+    else if (arg === "--dry-run") args.dryRun = true;
+    else if (arg === "--uninstall") args.uninstall = true;
+    else if (arg === "--user") args.scope = "user";
+    else if (arg === "--project") args.scope = "project";
+    else if (arg === "--print") args.print = true;
+    else if (arg === "--help" || arg === "-h") args.help = true;
+    else args.unknown = arg;
+  }
+  return args;
+}
+
+function usage() {
+  return [
+    "usage: npx @jitera/connect [--env=<environment>] [options]",
+    "",
+    "  --env=studio-stage   staging",
+    "  --env=studio-06      numbered pilot",
+    "  omit --env for production",
+    "",
+    "  --user               write user scoped config instead of project scoped",
+    "  --dry-run            report what would change without writing",
+    "  --uninstall          remove the jitera server",
+    "  --print              print resolved endpoints and exit",
+  ].join("\n");
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const out = process.stdout;
+
+  if (args.help) {
+    out.write(`${usage()}\n`);
+    return;
+  }
+
+  if (args.unknown) {
+    process.stderr.write(`error: unrecognised argument "${args.unknown}"\n${usage()}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  let mcpUrl;
+  let apiBaseUrl;
+  try {
+    mcpUrl = resolveMcpUrl(args.env);
+    apiBaseUrl = resolveApiBaseUrl(args.env);
+  } catch (error) {
+    if (error instanceof UnknownEnvironmentError) {
+      process.stderr.write(`error: ${error.message}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw error;
+  }
+
+  if (args.print) {
+    out.write(`${JSON.stringify({ mcpUrl, apiBaseUrl }, undefined, 2)}\n`);
+    return;
+  }
+
+  const context = { scope: args.scope, home: homedir(), cwd: process.cwd(), mcpUrl, dryRun: args.dryRun };
+  const detected = ADAPTERS.filter((adapter) => adapter.detect(context));
+
+  if (detected.length === 0) {
+    process.stderr.write(
+      `error: no supported assistant detected. Looked for: ${ADAPTERS.map((a) => a.label).join(", ")}.\n` +
+        `Claude Code and Codex install through their own plugin marketplaces, see the readme.\n`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const results = [];
+  for (const adapter of detected) {
+    try {
+      results.push({
+        adapter,
+        result: args.uninstall ? adapter.uninstall(context) : adapter.install(context),
+      });
+    } catch (error) {
+      if (error instanceof MalformedConfigError) {
+        process.stderr.write(`error: ${error.message}\n`);
+        process.exitCode = 1;
+        return;
+      }
+      throw error;
+    }
+  }
+
+  const verb = args.uninstall ? "removed from" : "written to";
+  for (const { adapter, result } of results) {
+    const state = result.changed ? verb : "already up to date in";
+    out.write(`${adapter.label}: ${state} ${result.path}\n`);
+  }
+
+  if (args.dryRun) {
+    out.write("\ndry run, nothing was written\n");
+    return;
+  }
+
+  if (!args.uninstall) {
+    out.write(`\nendpoint ${mcpUrl}\n`);
+    out.write("export JITERA_API_KEY=<your api key> before starting your assistant\n");
+  }
+}
+
+main();

package/content/checkpoint.md

@@ -0,0 +1,7 @@
+Checkpoint. If decisions, constraints, conventions, or corrections have come up
+in this session that are not yet in project memory, persist them now with
+`remember_jitera_memory`.
+
+Recall each entity first and re-send its full attribute list, so you update it
+rather than creating a duplicate. Skip anything already recorded in the
+repository or its git history.

package/content/instructions.md

@@ -0,0 +1,21 @@
+{{BRAND}} project context is available through this server: the project's
+memory, documentation, and source. Treat it as the source of truth for this
+project, not an optional lookup.
+
+Before answering a question about this project, and before planning or
+implementing anything, call `recall_jitera_memory` first. An empty result is
+normal and is not an error.
+
+Before writing a spec, design, or plan, search `documents/` with
+`resource_search` and read any match with `resource_read`. Update the existing
+document rather than creating a second one.
+
+When a decision is made, a constraint is discovered, or the user corrects you,
+persist it with `remember_jitera_memory`. Recall the entity first and re-send its
+full attribute list — entities are keyed on name plus type, so writing blind
+creates duplicates and replaces facts instead of adding them.
+
+Do not store anything already recorded in the repository or its git history.
+
+Domains: `documents/` is readable and writable; `sources/` and `uploads/` are
+read-only. Write tools require an API key created with read + write access.

package/content/session-start.md

@@ -0,0 +1,10 @@
+Project context tools are connected for this workspace: project documentation,
+source, and a shared project memory.
+
+Before your first substantive answer in this session, and before planning or
+implementing anything, call `recall_jitera_memory`. An empty result is normal and
+is not an error.
+
+As decisions are made, constraints are discovered, or you are corrected, persist
+them with `remember_jitera_memory`. Recall the entity first and re-send its full
+attribute list, so you update it rather than creating a duplicate.

package/hooks/hooks.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.mjs"],
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/scripts/stop.mjs"],
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/scripts/session-start.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function drainStdin() {
+  try {
+    readFileSync(0, "utf8");
+  } catch {
+    return;
+  }
+}
+
+function main() {
+  drainStdin();
+
+  let directive = "";
+  try {
+    directive = readFileSync(join(ROOT, "content", "session-start.md"), "utf8").trim();
+  } catch {
+    process.exit(0);
+  }
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: directive,
+      },
+    })
+  );
+}
+
+main();

package/hooks/scripts/stop.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const CHECKPOINT_EVERY_TURNS = 5;
+
+function readInput() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function main() {
+  const turn = readInput().turn_number;
+  if (!Number.isInteger(turn) || turn < 1) process.exit(0);
+  if (turn % CHECKPOINT_EVERY_TURNS !== 0) process.exit(0);
+
+  let directive = "";
+  try {
+    directive = readFileSync(join(ROOT, "content", "checkpoint.md"), "utf8").trim();
+  } catch {
+    process.exit(0);
+  }
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "Stop",
+        additionalContext: directive,
+      },
+    })
+  );
+}
+
+main();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@jitera/connect",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Connect AI coding assistants to Jitera projects: documentation, source, and shared project memory",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jitera-Product/connect.git"
+  },
+  "keywords": [
+    "jitera",
+    "mcp",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "cursor"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "jitera-connect": "./bin/jitera-connect.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "hooks/",
+    "content/",
+    "templates/",
+    ".claude-plugin/",
+    ".codex-plugin/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "validate": "node scripts/validate.mjs"
+  }
+}

package/skills/jitera-context/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: jitera-context
+description: Search and read {{BRAND}} project resources — documentation, source code, and uploaded files. Use when you need project context you do not already have, when the user refers to a file, document, or upload by name, and before answering questions about how this project works.
+license: Apache-2.0
+metadata:
+  author: jitera
+  version: "1.0"
+---
+
+# Reading {{BRAND}} project resources
+
+Three virtual domains:
+
+| Domain | Contents | Writable |
+| --- | --- | --- |
+| `documents/` | Project documentation — markdown, HTML, PDFs | yes |
+| `sources/` | Project source code | no |
+| `uploads/` | Uploaded files | no |
+
+## Searching
+
+```
+resource_search(pattern="documents/**/*.md", content="refund", limit=30, offset=0)
+```
+
+- `pattern` — a glob over virtual paths supporting `*`, `**`, and `?`. Omit the
+  domain prefix to search every domain: `resource_search(pattern="**/checkout*.*")`
+- `content` — a grep-style match inside files, supporting boolean expressions:
+  `content="(api OR rest) AND controller"`
+- Results are grouped by domain. Open a match with `resource_read`
+
+Search before reading. Do not guess paths.
+
+## Reading
+
+```
+resource_read(path="sources/frontend/src/App.tsx", line_from=1, line_number=300)
+```
+
+- A file path returns content with line numbers; a directory path returns a
+  listing. `resource_read(path="/")` lists the root
+- `line_from` is 1-indexed; `line_number` defaults to 300
+- For large PDFs read on the fly, `line_from` selects the starting **page**
+  rather than the line. The returned window ends with the `line_from` value to
+  pass in order to read further
+
+## Documents that are mostly images
+
+`analyze_document(url, requirements)` extracts information by looking at a
+document rather than reading its text. Use it for scanned PDFs, diagrams,
+screenshots, and spreadsheets where layout carries meaning.
+
+## Budget
+
+Search narrowly, then read the specific range you need. Reading whole large files
+to locate one function spends the context you need for the actual work.
+
+## Failures
+
+| Symptom | Cause | What to do |
+| --- | --- | --- |
+| A domain reports that it is disabled | That read domain is turned off for this agent or project | Tell the user which domain is disabled. Do not retry. |
+| Search returns nothing | Pattern too narrow, or the wrong domain | Drop the domain prefix and widen the glob before concluding the file is absent |
+| One path errors while a similar one works | The project has two path conventions and the editor form differs | Re-run `resource_search` and use the exact path it returns |

package/skills/jitera-memory/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: jitera-memory
+description: Recall and maintain {{BRAND}} project memory — stored decisions, constraints, conventions, and domain knowledge shared across the project. Use before planning or implementing anything, when the user refers to earlier work or past decisions, and after a decision is made, a constraint is discovered, or the user corrects you.
+license: Apache-2.0
+metadata:
+  author: jitera
+  version: "1.0"
+---
+
+# {{BRAND}} project memory
+
+Project memory is a graph of entities. Each entity has a `name`, a `type`, and a
+list of `attrs` — short factual statements. Entities reference each other with
+`[[id]]` links.
+
+Memory is shared with everyone working on the project. What you write, your
+teammates read.
+
+## Recall before you act
+
+Call `recall_jitera_memory` before:
+
+- starting any task in this project
+- planning or proposing an approach
+- making an architectural or naming decision
+- answering anything that refers to earlier work — "like we did before", "the
+  usual pattern", "what did we decide about…"
+
+An empty result is normal. It means nothing is stored yet, not that the call
+failed.
+
+### When the first recall comes back thin
+
+`recall_jitera_memory` filters entities by keywords extracted from `query`. Work
+down this ladder, stopping as soon as you have what you need:
+
+1. `recall_jitera_memory(query="<specific terms from the task>")`
+2. `recall_jitera_memory(query="<the subsystem or domain>")`
+3. `recall_jitera_memory()` with no query — returns every stored entity
+
+Do not conclude that memory is empty until step 3 returns nothing. Results
+containing `[[id]]` references mean related entities exist, and a broader query
+will surface them.
+
+## Remember when knowledge is created
+
+Persist with `remember_jitera_memory(name, type, attrs)` when:
+
+- a decision is made — including why it was chosen over the alternative
+- the user corrects you, or rejects an approach
+- you discover a constraint that is not obvious from the code: a rate limit, an
+  ordering requirement, a service that must be restarted, a deploy gotcha
+- you establish a convention future work should follow
+- a session ends with something worth carrying forward
+
+### Recall before you remember
+
+`remember_jitera_memory` upserts on `name` + `type`, and `attrs` **replaces** the
+existing list rather than appending to it. Writing without recalling first either
+fragments the graph into near-duplicates or silently drops facts:
+
+```
+Checkout Service (Service)  — attrs: [...]
+Checkout service (Service)  — attrs: [...]
+CheckoutService (Service)   — attrs: [...]
+```
+
+Procedure:
+
+1. `recall_jitera_memory(query="<entity name>")`
+2. If it exists, re-send it with the **full** attribute list — every existing
+   fact plus the new one
+3. If it does not exist, create it using the name form already used elsewhere in
+   the project
+
+### Shape of a good entity
+
+| Field | Guidance |
+| --- | --- |
+| `name` | The display name people actually use. Match existing casing. |
+| `type` | A stable category — `Service`, `Decision`, `Constraint`, `Convention`, `Person`, `System`. Reuse types already in the graph. |
+| `attrs` | Short, self-contained statements. One fact per entry. |
+
+Good:
+
+```
+name:  "Checkout Service"
+type:  "Service"
+attrs: ["Owns payment capture and refunds",
+        "Reaches Stripe through the billing gateway, never directly",
+        "Refunds are idempotent on order id, not payment id"]
+```
+
+Poor — vague, and re-derivable from the code:
+
+```
+name:  "checkout"
+type:  "thing"
+attrs: ["handles checkout stuff", "has files in src/checkout"]
+```
+
+## What not to store
+
+- Anything derivable from the repository or its git history — file layout,
+  function signatures, what a past commit changed
+- Transient state — what you are doing right now, a branch name, a test you are
+  part-way through fixing
+- Secrets, credentials, tokens, or customer personal data
+- Long prose. If it needs paragraphs, write a document (see the `jitera-specs`
+  skill) and store a one-line pointer to it in memory
+
+## Failures
+
+| Symptom | Cause | What to do |
+| --- | --- | --- |
+| `remember_jitera_memory` rejected as read-only | The API key was created with read access only | Tell the user the key needs read + write access, created in project settings. Do not retry. |
+| Recall returns unrelated entities | Keyword extraction matched loosely | Narrow the query, or recall with no query and filter the results yourself |
+| Recall is still empty at step 3 | Memory genuinely is empty | Proceed, and record what you learn as you go |

package/skills/jitera-setup/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: jitera-setup
+description: Diagnose a broken {{BRAND}} connection — missing tools, authentication failures, read-only API keys, or the wrong project. Use when {{BRAND}} tools are absent from the tool list, when a call fails with an authentication or authorization error, or when the data returned belongs to a different project than expected.
+license: Apache-2.0
+metadata:
+  author: jitera
+  version: "1.0"
+---
+
+# Diagnosing a {{BRAND}} connection
+
+Work through these in order. Report the specific cause you find — never tell the
+user only that something failed.
+
+## 1. Are the tools present?
+
+If `resource_search`, `resource_read`, and `recall_jitera_memory` are missing from
+your tool list, the MCP server is not connected at all. This is not a permissions
+problem and no API key will fix it.
+
+Ask the user to confirm the server is configured, then to restart the assistant.
+Most clients load MCP servers only at startup.
+
+## 2. Does any call succeed?
+
+Try the cheapest possible read:
+
+```
+resource_read(path="/")
+```
+
+| Result | Meaning |
+| --- | --- |
+| A directory listing | Connection and key are fine; the problem is elsewhere |
+| Unauthorized or authentication error | The key is missing, wrong, revoked, or expired |
+| An empty listing | Connected, but the project has no resources yet |
+
+## 3. Is the key read-only?
+
+A read that works alongside a write that fails with a read-only message means the
+key was created with read access only.
+
+Writes need a key created with **read + write** access. The access level is fixed
+when the key is created and cannot be changed afterwards, so this needs a new key
+from project settings.
+
+## 4. Is it the right project?
+
+An API key is bound to one project. If the resources returned belong to a
+different project than the user expects, the key belongs to that other project.
+
+Confirm with `resource_read(path="/")` and describe what you see back to the user
+so they can recognise it.
+
+## 5. Is memory scoped more narrowly than expected?
+
+A key bound to a specific agent sees only that agent's memory partition. A
+project-level key sees project-wide memory. If recall returns less than the user
+expects, the key is probably agent-scoped.
+
+## What not to do
+
+- Do not retry an authentication failure or a read-only rejection — neither is
+  transient, and retrying only delays the real fix
+- Do not invent a workaround, such as writing a spec into the local repository
+  when the intent was to store it in the project. State what is blocked and why

package/skills/jitera-specs/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: jitera-specs
+description: Write, find, and maintain specifications and design documents in {{BRAND}} project documentation. Use before implementing a feature, to find the spec that already describes it; when asked to write a spec, design, plan, or decision record; and when an implementation has diverged from the document describing it.
+license: Apache-2.0
+metadata:
+  author: jitera
+  version: "1.0"
+---
+
+# Specs in {{BRAND}} documentation
+
+Specs live in the `documents/` domain and are shared with the whole project. They
+are living documents — written once, then read and revised as the work proceeds.
+
+`documents/` is the only writable domain. `sources/` and `uploads/` are read-only.
+
+## Before implementing anything
+
+1. `resource_search(pattern="documents/**/*.md", content="<feature terms>")`
+2. `resource_read(path="documents/<match>")` on anything plausible
+3. Write a new spec only when nothing covers it
+
+Writing a second spec for something already specified is the most common failure
+here. Two documents describing the same feature diverge immediately, and
+afterwards neither can be trusted.
+
+## Writing a spec
+
+```
+resource_write(
+  path="documents/specs/checkout-refunds.md",
+  operation="create",
+  content="<full markdown>"
+)
+```
+
+Path conventions:
+
+- `documents/specs/<feature>.md` — specifications and designs
+- `documents/decisions/<topic>.md` — decision records
+
+Follow whatever convention the project already uses. Check with
+`resource_search(pattern="documents/**")` before inventing one.
+
+## Updating a spec
+
+```
+resource_write(
+  path="documents/specs/checkout-refunds.md",
+  operation="update",
+  content="<full markdown>"
+)
+```
+
+- `update` resolves the document by `path`, or by `uuid` when you pass one
+- Updates apply as a diff by default. Pass `force_replace=true` only when you
+  intend to replace the whole document
+- Prefer updating over creating a second document, even for large changes
+
+Update the spec when the implementation diverges from it, when a decision it
+records is reversed, or when you find it was wrong. A spec that no longer matches
+the code is worse than no spec, because it is trusted and wrong.
+
+## Moving and deleting
+
+```
+resource_write(path="documents/old.md", operation="move",
+               new_path="documents/specs/new.md")
+resource_write(path="documents/obsolete.md", operation="delete")
+```
+
+## Generated drafts
+
+Passing `requirements` instead of `content` has the document generated from a
+description rather than written by you:
+
+```
+resource_write(
+  path="documents/specs/checkout-refunds.md",
+  requirements="Specification for idempotent refunds, keyed on order id",
+  format="md"
+)
+```
+
+Write `content` yourself by default. Use `requirements` only when the user asks
+for a generated draft.
+
+## After writing
+
+Record that the spec exists, so a future session finds it without searching. See
+the `jitera-memory` skill for the recall-before-remember rule:
+
+```
+remember_jitera_memory(
+  name="Refunds specification",
+  type="Decision",
+  attrs=["Specified in documents/specs/checkout-refunds.md",
+         "Refunds are idempotent on order id"]
+)
+```
+
+## Failures
+
+| Symptom | Cause | What to do |
+| --- | --- | --- |
+| Write rejected as read-only | The API key has read access only | Tell the user the key needs read + write access, created in project settings. Do not retry. |
+| Write to `sources/` or `uploads/` fails | Those domains are read-only by design | Write to `documents/` instead |
+| Write to a linked project's path fails | The link to that project does not grant write access | Ask the user to adjust the project link, or write into the current project |

package/src/adapters/cursor.mjs

@@ -0,0 +1,56 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { mergeServer, readConfig, removeServer, writeConfig } from "../mcp-config.mjs";
+
+export const SERVER_NAME = "jitera";
+const CONFIG_KEY = "mcpServers";
+const API_KEY_ENV = "JITERA_API_KEY";
+
+export const cursor = {
+  id: "cursor",
+  label: "Cursor",
+  secretStrategy: "env",
+
+  detect({ home }) {
+    return existsSync(join(home, ".cursor"));
+  },
+
+  mcpConfigPath({ scope, home, cwd }) {
+    return scope === "user"
+      ? join(home, ".cursor", "mcp.json")
+      : join(cwd, ".cursor", "mcp.json");
+  },
+
+  skillsDirs({ scope, home, cwd }) {
+    return scope === "user"
+      ? [join(home, ".agents", "skills"), join(home, ".claude", "skills")]
+      : [join(cwd, ".agents", "skills"), join(cwd, ".claude", "skills")];
+  },
+
+  serverEntry({ mcpUrl }) {
+    return {
+      type: "http",
+      url: mcpUrl,
+      headers: {
+        Authorization: `Bearer \${env:${API_KEY_ENV}}`,
+      },
+    };
+  },
+
+  install({ scope, home, cwd, mcpUrl, dryRun }) {
+    const path = this.mcpConfigPath({ scope, home, cwd });
+    const before = readConfig(path);
+    const after = mergeServer(before, CONFIG_KEY, SERVER_NAME, this.serverEntry({ mcpUrl }));
+    if (!dryRun) writeConfig(path, after);
+    return { path, config: after, changed: JSON.stringify(before) !== JSON.stringify(after) };
+  },
+
+  uninstall({ scope, home, cwd, dryRun }) {
+    const path = this.mcpConfigPath({ scope, home, cwd });
+    const before = readConfig(path);
+    const after = removeServer(before, CONFIG_KEY, SERVER_NAME);
+    if (!dryRun) writeConfig(path, after);
+    return { path, config: after, changed: JSON.stringify(before) !== JSON.stringify(after) };
+  },
+};

package/src/environments.mjs

@@ -0,0 +1,46 @@
+const PRODUCTION_GATEWAY = "https://gateway-proxy.jitera.app";
+const STAGE_GATEWAY = "https://jitera-stage-pilot.jitera.app";
+const PILOT_GATEWAY = "https://kong-proxy-pilot.jitera.app";
+
+const PILOT_PATTERN = /^studio-(\d{1,2})$/;
+
+export const SUPPORTED_ENVIRONMENTS = ["studio", "studio-stage", "studio-01", "studio-06"];
+
+export class UnknownEnvironmentError extends Error {
+  constructor(value) {
+    super(
+      `unknown environment "${value}". Supported: omit the flag for production, ` +
+        `--env=studio-stage for staging, or --env=studio-NN for a numbered pilot ` +
+        `such as --env=studio-06.`
+    );
+    this.name = "UnknownEnvironmentError";
+    this.value = value;
+  }
+}
+
+function resolveBase(environment) {
+  const name = String(environment ?? "").trim().toLowerCase();
+
+  if (name === "" || name === "studio" || name === "production") {
+    return `${PRODUCTION_GATEWAY}/gateway/boost`;
+  }
+
+  if (name === "studio-stage") {
+    return `${STAGE_GATEWAY}/gateway/boost`;
+  }
+
+  const pilot = PILOT_PATTERN.exec(name);
+  if (pilot) {
+    return `${PILOT_GATEWAY}/gateway/boost-${pilot[1].padStart(2, "0")}`;
+  }
+
+  throw new UnknownEnvironmentError(environment);
+}
+
+export function resolveMcpUrl(environment) {
+  return `${resolveBase(environment)}/mcp`;
+}
+
+export function resolveApiBaseUrl(environment) {
+  return `${resolveBase(environment)}/v1`;
+}

package/src/mcp-config.mjs

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export class MalformedConfigError extends Error {
+  constructor(path, cause) {
+    super(
+      `${path} exists but is not valid JSON, so it cannot be merged safely. ` +
+        `Fix or move the file, then run again. Parser said: ${cause.message}`
+    );
+    this.name = "MalformedConfigError";
+    this.path = path;
+  }
+}
+
+export function readConfig(path) {
+  if (!existsSync(path)) return {};
+  const raw = readFileSync(path, "utf8");
+  if (raw.trim() === "") return {};
+  try {
+    return JSON.parse(raw);
+  } catch (cause) {
+    throw new MalformedConfigError(path, cause);
+  }
+}
+
+export function mergeServer(config, key, name, server) {
+  const next = { ...config };
+  next[key] = { ...(next[key] ?? {}) };
+  next[key][name] = server;
+  return next;
+}
+
+export function removeServer(config, key, name) {
+  const next = { ...config };
+  if (!next[key]) return next;
+  next[key] = { ...next[key] };
+  delete next[key][name];
+  if (Object.keys(next[key]).length === 0) delete next[key];
+  return next;
+}
+
+export function writeConfig(path, config) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, undefined, 2)}\n`, "utf8");
+}

package/templates/AGENTS.md.tmpl

@@ -0,0 +1,22 @@
+<!-- BEGIN JITERA CONNECT -->
+## {{BRAND}} project context
+
+This repository is connected to a {{BRAND}} project. Documentation, source, and a
+shared project memory are available through the `jitera` MCP server.
+
+Before planning or implementing anything, call `recall_jitera_memory`. An empty
+result is normal and is not an error.
+
+Before writing a spec or design, search `documents/` with `resource_search` and
+read any match with `resource_read`. Update the existing document rather than
+creating a second one.
+
+When a decision is made, a constraint is discovered, or you are corrected,
+persist it with `remember_jitera_memory`. Recall the entity first and re-send its
+full attribute list, because entities are keyed on name plus type.
+
+`documents/` is readable and writable. `sources/` and `uploads/` are read-only.
+
+Claude Code does not read this file. Add `@AGENTS.md` to `CLAUDE.md` so both read
+the same instructions.
+<!-- END JITERA CONNECT -->