gemcode 0.3.85__py3-none-any.whl → 0.3.86__py3-none-any.whl

gemcode/agent.py

@@ -103,14 +103,15 @@ def _chain_before_model_callbacks(*callbacks):
 
 def _load_gemini_md(project_root: Path) -> str:
   """
-  Load GEMINI.md / .gemcode/NOTES.md from a interactive CLI–style hierarchy.
+  Load project instruction markdown / .gemcode/NOTES.md from a interactive CLI–style hierarchy.
 
   Priority (later entries override earlier ones, all are concatenated):
     1. ~/.gemcode/GEMINI.md           — user-global instructions (all projects)
-    2. Walk UP from project_root: each directory's GEMINI.md / .gemcode/GEMINI.md
+    2. Walk UP from project_root: each directory's `gemcode.md` / `GEMINI.md`
        (org-level files at higher dirs, project-level at project_root)
-    3. project_root/GEMINI.md         — the primary project instructions
-    4. project_root/.gemcode/GEMINI.md — alternative location
+    3. project_root/gemcode.md        — the primary project instructions
+    4. project_root/GEMINI.md         — backward-compatible legacy location
+    5. project_root/.gemcode/GEMINI.md — alternative location
     5. project_root/.gemcode/notes.md  — agent auto-generated notes (read-only context)
 
   Max total: 80,000 chars.  Each file is capped at 30,000 chars.
@@ -118,7 +119,14 @@ def _load_gemini_md(project_root: Path) -> str:
   """
   import re
 
-  _NAMES = ("GEMINI.md", "gemini.md", ".gemcode/GEMINI.md")
+  _NAMES = (
+    "gemcode.md",
+    "GEMCODE.md",
+    "GEMINI.md",
+    "gemini.md",
+    ".gemcode/GEMINI.md",
+    ".gemcode/gemini.md",
+  )
   _FILE_CAP = 30_000
   _TOTAL_CAP = 80_000
   _COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
@@ -162,8 +170,15 @@ def _load_gemini_md(project_root: Path) -> str:
     for name in _NAMES:
       _add(ancestor / name)
 
-  # 3+4. Project-root level instructions (primary location)
-  for name in ("GEMINI.md", "gemini.md", ".gemcode/GEMINI.md", ".gemcode/gemini.md"):
+  # 3+5. Project-root level instructions (primary location + compatibility)
+  for name in (
+    "gemcode.md",
+    "GEMCODE.md",
+    "GEMINI.md",
+    "gemini.md",
+    ".gemcode/GEMINI.md",
+    ".gemcode/gemini.md",
+  ):
     _add(project_root / name)
 
   # 5. Agent-generated notes (informational context, not instructions)
@@ -312,6 +327,11 @@ def _build_runtime_facts(cfg: GemCodeConfig) -> str:
         "\n\n## VeoMem recall (auto-captured, progressive)\n"
         "This section is automatically generated from prior tool usage and summaries. "
         "Treat it as helpful context; do not restate it verbatim to the user.\n"
+        "If you need deeper details about a specific prior observation, use the "
+        "3-step retrieval flow with tools:\n"
+        "- `veomem_search(query=...)` → get an index of relevant observation IDs\n"
+        "- `veomem_timeline(id=...)` → get compact neighbors around an anchor ID\n"
+        "- `veomem_get_observations(ids=...)` → fetch full text for selected IDs\n"
         f"{t.strip()}\n"
       )
   except Exception:

gemcode/cli.py

@@ -130,18 +130,30 @@ def _initialize_gemcode_project(cfg: GemCodeConfig) -> None:
   """
   root = cfg.project_root.resolve()
   gem_dir = root / ".gemcode"
+  gemcode_md = root / "gemcode.md"
   already_there = gem_dir.is_dir()
   try:
     gem_dir.mkdir(parents=True, exist_ok=True)
   except OSError as e:
     print(f"[gemcode] warning: could not create {gem_dir}: {e}", file=sys.stderr)
     return
+  if not gemcode_md.exists():
+    try:
+      gemcode_md.write_text(
+        "# Project instructions\n\n"
+        "- Describe the project purpose here.\n"
+        "- Add build, test, and lint commands.\n"
+        "- Add architecture notes and conventions GemCode should follow.\n",
+        encoding="utf-8",
+      )
+    except OSError as e:
+      print(f"[gemcode] warning: could not create {gemcode_md}: {e}", file=sys.stderr)
   if not already_there:
     print(
         "\n── GemCode · Project folder ready ──\n"
         f"  Workspace: {root}\n"
         f"  Config & session data: {gem_dir}/\n"
-        "  Optional: add GEMINI.md in the repo root for project context.\n"
+        f"  Project instructions: {gemcode_md.name}\n"
         "── Ready. ──\n",
         file=sys.stderr,
     )

gemcode/repl_slash.py

@@ -1172,15 +1172,15 @@ async def process_repl_slash(
     return ReplSlashResult(skip_model_turn=True)
 
   if name == "init":
-    gemini_md = cfg.project_root / "GEMINI.md"
-    if gemini_md.exists() and (sc.args or "").strip().lower() not in ("force", "overwrite", "-f"):
-      out(f"GEMINI.md already exists at {gemini_md}.")
+    gemcode_md = cfg.project_root / "gemcode.md"
+    if gemcode_md.exists() and (sc.args or "").strip().lower() not in ("force", "overwrite", "-f"):
+      out(f"gemcode.md already exists at {gemcode_md}.")
       out("Use /init force to regenerate it, or edit it manually.")
       out()
       return ReplSlashResult(skip_model_turn=True)
-    # Dispatch to the model to analyze the project and write GEMINI.md.
+    # Dispatch to the model to analyze the project and write gemcode.md.
     init_prompt = (
-      "Analyze this codebase and generate a GEMINI.md file for me.\n\n"
+      "Analyze this codebase and generate a gemcode.md file for me.\n\n"
       "To do this:\n"
       "1. Run `list_directory('.')` to understand the project structure\n"
       "2. Read `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `README.md` "
@@ -1188,9 +1188,9 @@ async def process_repl_slash(
       "3. Look at the source directory structure (src/, lib/, app/, etc.)\n"
       "4. Check for test directories and test runner config\n"
       "5. Look for linting/formatting config files (.eslintrc, .prettierrc, ruff.toml, etc.)\n\n"
-      "Write **only** to `GEMINI.md` at the project root. Do **not** create "
+      "Write **only** to `gemcode.md` at the project root. Do **not** create "
       "`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, or similar.\n\n"
-      "Then write a GEMINI.md file at the project root containing:\n"
+      "Then write a gemcode.md file at the project root containing:\n"
       "# Project Name\n"
       "One-sentence description.\n\n"
       "## Build & Test\n"
@@ -1208,10 +1208,10 @@ async def process_repl_slash(
       "## Workflow\n"
       "- Any git branching rules from README or CONTRIBUTING\n"
       "- PR/commit conventions\n\n"
-      "Keep it under 200 lines. Write the file to GEMINI.md now."
+      "Keep it under 200 lines. Write the file to gemcode.md now."
     )
-    out("Analyzing project to generate GEMINI.md…")
-    out("(GemCode will read the project structure and write a starting GEMINI.md)")
+    out("Analyzing project to generate gemcode.md…")
+    out("(GemCode will read the project structure and write a starting gemcode.md)")
     out()
     return ReplSlashResult(model_prompt=init_prompt)
 

gemcode/session_runtime.py

@@ -404,6 +404,46 @@ def create_runner(cfg: GemCodeConfig, extra_tools: list | None = None) -> Runner
   except Exception:
     pass  # OpenAPIToolset not in this ADK version — continue without
 
+  # ── AFC compatibility prompt (optional) ───────────────────────────────────
+  # Gemini Automatic Function Calling (AFC) only works when the tool list is
+  # composed of Python callables. Some ADK toolsets (MCP/OpenAPI/built-in
+  # declarations) may be non-callable and cause AFC to be disabled.
+  #
+  # If we're in an interactive terminal and the user opted into prompting,
+  # ask whether to keep "all tools" (AFC disabled) or restrict to callables
+  # (AFC enabled).
+  try:
+    import os
+    import sys
+
+    prompt_afc = os.environ.get("GEMCODE_AFC_PROMPT", "1").strip().lower() in ("1", "true", "yes", "on")
+    if prompt_afc and hasattr(sys.stdin, "isatty") and sys.stdin.isatty():
+      tools_list = list(merged_extra_tools or [])
+      noncallable = [t for t in tools_list if not callable(t)]
+      if noncallable and getattr(cfg, "_afc_choice", None) not in ("all", "callables"):
+        print(
+          "\n[gemcode] AFC compatibility\n"
+          "Gemini Automatic Function Calling (AFC) works best with Python callables only.\n"
+          "Some enabled toolsets appear non-callable, which can disable AFC.\n\n"
+          "Choose tool mode for this session:\n"
+          "  [Enter] all tools (recommended; AFC may be disabled)\n"
+          "  c       callable-only tools (keeps AFC; disables MCP/OpenAPI/toolsets)\n",
+          file=sys.stderr,
+        )
+        try:
+          ans = input("afc> ").strip().lower()
+        except EOFError:
+          ans = ""
+        if ans.startswith("c"):
+          object.__setattr__(cfg, "_afc_choice", "callables")
+        else:
+          object.__setattr__(cfg, "_afc_choice", "all")
+
+      if getattr(cfg, "_afc_choice", None) == "callables":
+        merged_extra_tools = [t for t in tools_list if callable(t)] or None
+  except Exception:
+    pass
+
   # Computer-use: ADK ComputerUseToolset backed by our Playwright BrowserComputer.
   # Probe Playwright BEFORE building the agent so model routing (which runs
   # inside build_root_agent → pick_effective_model) never switches to

gemcode/tools/__init__.py

@@ -20,6 +20,7 @@ from gemcode.checkpoints import list_checkpoints as _list_checkpoints, undo_chec
 from gemcode.tools.curated_memory import make_curated_memory_tools
 from gemcode.tools.compress_memory import make_compress_memory_tool
 from gemcode.tools.skills import make_skill_tools
+from gemcode.tools.veomem_tools import make_veomem_tools
 
 
 def _get_load_memory_tool():
@@ -153,12 +154,19 @@ def build_function_tools(cfg: GemCodeConfig, *, include_subtask: bool = True) ->
     read_curated_memory,
     # Optional: compress memory files (markdown only; safe guards apply)
     compress_memory_file,
+    # Optional: VeoMem recall tools (3-step search/timeline/fetch).
+    # Enabled via GEMCODE_VEOMEM=1.
     # GemSkills (on-demand playbooks)
     list_skills,
     load_skill,
     skills_manifest,
   ]
 
+  try:
+    tools.extend(make_veomem_tools(cfg))
+  except Exception:
+    pass
+
   # ADK load_memory: explicit on-demand memory search (complements preload_memory).
   # Only add when memory is enabled so the tool doesn't appear when there's no
   # memory service to call into.

gemcode/veomem_bridge.py

@@ -24,6 +24,16 @@ def _summarize_tool_result(result: dict[str, Any]) -> str:
   if result.get("error"):
     e = str(result.get("error"))
     return f"error: {e[:800]}"
+
+  def _clip_str(x: Any, n: int) -> str:
+    if x is None:
+      return ""
+    s = str(x)
+    s = s.strip()
+    if len(s) <= n:
+      return s
+    return s[:n].rstrip() + "…"
+
   parts: list[str] = []
   for k in ("exit_code", "path", "backup_path", "count", "chars_before", "chars_after"):
     if k in result:
@@ -31,7 +41,26 @@ def _summarize_tool_result(result: dict[str, Any]) -> str:
   for k in ("stdout", "stderr"):
     v = result.get(k)
     if isinstance(v, str) and v.strip():
-      parts.append(f"{k}={v.strip()[:200]}{'…' if len(v) > 200 else ''}")
+      parts.append(f"{k}={_clip_str(v, 800)}")
+
+  # Web search results can be high-signal but are structured; make them searchable.
+  try:
+    results = result.get("results")
+    if isinstance(results, list) and results:
+      pieces: list[str] = []
+      for r in results[:5]:
+        if not isinstance(r, dict):
+          continue
+        title = _clip_str(r.get("title"), 120)
+        url = _clip_str(r.get("url"), 140)
+        snippet = _clip_str(r.get("snippet"), 180)
+        if title or url or snippet:
+          pieces.append(f"{title} ({url}) {snippet}".strip())
+      if pieces:
+        parts.append("results=[" + " | ".join(pieces) + "]")
+  except Exception:
+    pass
+
   return " ".join(parts).strip()
 
 

gemcode-0.3.86.dist-info/METADATA

@@ -0,0 +1,416 @@
+Metadata-Version: 2.4
+Name: gemcode
+Version: 0.3.86
+Summary: Local-first coding agent on Google Gemini + ADK
+Author: GemCode Contributors
+License:                                  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.
+        
+           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.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor.
+        
+           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.
+        
+           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, shall any Contributor be liable
+              to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages arising in any way out of the
+              use of the Work.
+        
+           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.
+        
+           END OF TERMS AND CONDITIONS
+        
+        
+Project-URL: Homepage, https://github.com/spiderdev27/GemCode
+Project-URL: Repository, https://github.com/spiderdev27/GemCode
+Project-URL: Issues, https://github.com/spiderdev27/GemCode/issues
+Keywords: ai,agent,coding,gemini,adk,cli,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-adk>=1.0.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: prompt_toolkit>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Dynamic: license-file
+
+# GemCode User Manual
+
+This document is the primary user-facing manual for GemCode. It explains the product at a high level and points to the subsystem-specific documentation pages that provide production-grade depth.
+
+## What GemCode is
+GemCode is a local-first coding agent built around Google Gemini and the Google Agent Development Kit (ADK). It operates against a chosen project root and combines:
+- a configuration model
+- a runtime runner
+- a root language-model agent
+- a configurable tool inventory
+- project-local state under `.gemcode/`
+
+GemCode is designed for repository-native work rather than copy-paste chat workflows.
+
+## Runtime modes
+
+| Mode | Purpose |
+|---|---|
+| One-shot CLI | Single prompt/response runs |
+| REPL | Stateful terminal interaction |
+| TUI | Scrollback terminal UI over the REPL runtime |
+| IDE stdio | Editor integration over JSONL stdin/stdout |
+| Kaira | Priority-queue scheduler for background jobs |
+| Live audio | Microphone-driven Gemini Live sessions |
+
+## Recommended reading order
+
+### 1. Setup and first use
+- [`../docs/install.md`](../docs/install.md)
+
+### 2. Interactive use
+- [`../docs/cli-and-repl.md`](../docs/cli-and-repl.md)
+
+### 3. Configuration and local assets
+- [`../docs/configuration.md`](../docs/configuration.md)
+
+### 4. Tooling and safety model
+- [`../docs/tools-and-permissions.md`](../docs/tools-and-permissions.md)
+
+### 5. Optional capability bundles
+- [`../docs/capabilities.md`](../docs/capabilities.md)
+
+### 6. Integrations
+- [`../docs/integrations.md`](../docs/integrations.md)
+- [`../docs/web-ui-contract.md`](../docs/web-ui-contract.md)
+
+### 7. Operations and release
+- [`../docs/operations.md`](../docs/operations.md)
+
+### 8. `.gemcode/` state reference
+- [`../docs/reference-gemcode-state.md`](../docs/reference-gemcode-state.md)
+
+### 9. Architecture deep dive
+- [`../docs/architecture.md`](../docs/architecture.md)
+
+## Quickstart
+
+### Install
+```bash
+cd gemcode
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -e ".[dev]"
+```
+
+### Set your API key
+```bash
+export GOOGLE_API_KEY="your-key"
+```
+
+### Start GemCode against a project
+```bash
+gemcode -C /path/to/project
+```
+
+### One-shot run
+```bash
+gemcode -C /path/to/project "Explain this repository"
+```
+
+### Mutating run
+```bash
+gemcode -C /path/to/project --yes "Fix the failing tests"
+```
+
+## Essential concepts
+
+### Project root
+Every GemCode run is anchored to a project root. This determines:
+- what files are visible
+- where `.gemcode/` state is stored
+- what instruction files are loaded
+- which repo-local assets are active
+
+### `.gemcode/`
+GemCode stores project-local state under `.gemcode/`, including:
+- sessions
+- logs
+- artifacts
+- memory
+- skills
+- rules
+- output styles
+- hooks
+- integration config
+
+Reference:
+- [`../docs/reference-gemcode-state.md`](../docs/reference-gemcode-state.md)
+
+### Project instruction files
+GemCode supports project instruction files loaded by the agent layer. The live code treats `gemcode.md` as the primary project instruction file and supports `GEMINI.md` as a compatibility path.
+
+Reference:
+- [`../docs/configuration.md`](../docs/configuration.md)
+
+### GemSkills
+GemSkills are reusable prompt playbooks stored under:
+- `.gemcode/skills/<name>/SKILL.md`
+- `~/.gemcode/skills/<name>/SKILL.md`
+
+They support:
+- creation
+- session loading
+- one-shot invocation
+- iterative editing
+
+### Permissions
+GemCode combines:
+- workspace trust
+- permission mode
+- allow/deny settings
+- blanket approval flags
+- interactive approval prompts
+
+Reference:
+- [`../docs/tools-and-permissions.md`](../docs/tools-and-permissions.md)
+
+## Common commands
+
+### Inspect models
+```bash
+gemcode models
+```
+
+### Start the REPL
+```bash
+gemcode -C .
+```
+
+### Attach a file to a one-shot turn
+```bash
+gemcode -C . --attach ./report.pdf "Summarize this"
+```
+
+### Run the scheduler
+```bash
+gemcode kaira -C .
+```
+
+### Start the IDE bridge
+```bash
+gemcode ide --stdio
+```
+
+### Run live audio
+```bash
+gemcode live-audio -C .
+```
+
+## REPL command highlights
+
+| Command | Purpose |
+|---|---|
+| `/help` | Command summary |
+| `/status` | Model, capabilities, context, and runtime telemetry |
+| `/context` | Context pressure and prompt budget telemetry |
+| `/cost` | Token and cost estimate summary |
+| `/attach` | Queue file attachments for the next turn |
+| `/trust` | Manage workspace trust |
+| `/init` | Generate project instructions |
+| `/skills` | List skills |
+| `/gemskill` | Load a skill into the session prompt |
+| `/style` | Set session output style |
+| `/rules` | Inspect active rules |
+| `/diff` | Show current diff/checkpoint diff |
+| `/rewind` | Restore checkpoints |
+| `/review` | Run a review workflow |
+| `/eval` | Run evaluation gates |
+| `/kaira` | Show scheduler usage help |
+
+Detailed behavior:
+- [`../docs/cli-and-repl.md`](../docs/cli-and-repl.md)
+
+## Capability overview
+
+| Capability | What it adds |
+|---|---|
+| Deep research | research-focused tool routing and optional dedicated model path |
+| Embeddings | semantic search and optional embedding-backed memory |
+| Memory | retrieval-oriented persistent memory |
+| Browser/computer use | Playwright-backed browser automation and inspection |
+| Live audio | Gemini Live microphone sessions |
+
+Detailed behavior:
+- [`../docs/capabilities.md`](../docs/capabilities.md)
+
+## Integrations overview
+
+| Integration | Entry point |
+|---|---|
+| IDE bridge | `gemcode ide --stdio` |
+| Web/SSE | documented in `docs/web-ui-contract.md` |
+| MCP | `.gemcode/mcp.json` |
+| OpenAPI | `.gemcode/openapi/` |
+
+Detailed behavior:
+- [`../docs/integrations.md`](../docs/integrations.md)
+
+## Release and maintenance
+Package version lives in:
+- `gemcode/pyproject.toml`
+
+Release operations, troubleshooting, and PyPI workflow are documented in:
+- [`../docs/operations.md`](../docs/operations.md)
+
+## Documentation policy
+This manual is intentionally concise. The detailed production documentation lives under `docs/` and is organized by subsystem and operator concern so it can stay accurate as GemCode evolves.