@anthropic-field/core 0.1.0

package/dist/docs/cli/session-management.md

@@ -0,0 +1,158 @@
+# Session Management
+
+Gemini CLI includes robust session management features that automatically save
+your conversation history. This allows you to interrupt your work and resume
+exactly where you left off, review past interactions, and manage your
+conversation history effectively.
+
+## Automatic Saving
+
+Every time you interact with Gemini CLI, your session is automatically saved.
+This happens in the background without any manual intervention.
+
+- **What is saved:** The complete conversation history, including:
+  - Your prompts and the model's responses.
+  - All tool executions (inputs and outputs).
+  - Token usage statistics (input/output/cached, etc.).
+  - Assistant thoughts/reasoning summaries (when available).
+- **Location:** Sessions are stored in `~/.gemini/tmp/<project_hash>/chats/`.
+- **Scope:** Sessions are project-specific. Switching directories to a different
+  project will switch to that project's session history.
+
+## Resuming Sessions
+
+You can resume a previous session to continue the conversation with all prior
+context restored.
+
+### From the Command Line
+
+When starting the CLI, you can use the `--resume` (or `-r`) flag:
+
+- **Resume latest:**
+
+  ```bash
+  gemini --resume
+  ```
+
+  This immediately loads the most recent session.
+
+- **Resume by index:** First, list available sessions (see
+  [Listing Sessions](#listing-sessions)), then use the index number:
+
+  ```bash
+  gemini --resume 1
+  ```
+
+- **Resume by ID:** You can also provide the full session UUID:
+  ```bash
+  gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890
+  ```
+
+### From the Interactive Interface
+
+While the CLI is running, you can use the `/resume` slash command to open the
+**Session Browser**:
+
+```text
+/resume
+```
+
+This opens an interactive interface where you can:
+
+- **Browse:** Scroll through a list of your past sessions.
+- **Preview:** See details like the session date, message count, and the first
+  user prompt.
+- **Search:** Press `/` to enter search mode, then type to filter sessions by ID
+  or content.
+- **Select:** Press `Enter` to resume the selected session.
+
+## Managing Sessions
+
+### Listing Sessions
+
+To see a list of all available sessions for the current project from the command
+line:
+
+```bash
+gemini --list-sessions
+```
+
+Output example:
+
+```text
+Available sessions for this project (3):
+
+  1. Fix bug in auth (2 days ago) [a1b2c3d4]
+  2. Refactor database schema (5 hours ago) [e5f67890]
+  3. Update documentation (Just now) [abcd1234]
+```
+
+### Deleting Sessions
+
+You can remove old or unwanted sessions to free up space or declutter your
+history.
+
+**From the Command Line:** Use the `--delete-session` flag with an index or ID:
+
+```bash
+gemini --delete-session 2
+```
+
+**From the Session Browser:**
+
+1.  Open the browser with `/resume`.
+2.  Navigate to the session you want to remove.
+3.  Press `x`.
+
+## Configuration
+
+You can configure how Gemini CLI manages your session history in your
+`settings.json` file.
+
+### Session Retention
+
+To prevent your history from growing indefinitely, you can enable automatic
+cleanup policies.
+
+```json
+{
+  "general": {
+    "sessionRetention": {
+      "enabled": true,
+      "maxAge": "30d", // Keep sessions for 30 days
+      "maxCount": 50 // Keep the 50 most recent sessions
+    }
+  }
+}
+```
+
+- **`enabled`**: (boolean) Master switch for session cleanup. Default is
+  `false`.
+- **`maxAge`**: (string) Duration to keep sessions (e.g., "24h", "7d", "4w").
+  Sessions older than this will be deleted.
+- **`maxCount`**: (number) Maximum number of sessions to retain. The oldest
+  sessions exceeding this count will be deleted.
+- **`minRetention`**: (string) Minimum retention period (safety limit). Defaults
+  to `"1d"`; sessions newer than this period are never deleted by automatic
+  cleanup.
+
+### Session Limits
+
+You can also limit the length of individual sessions to prevent context windows
+from becoming too large and expensive.
+
+```json
+{
+  "model": {
+    "maxSessionTurns": 100
+  }
+}
+```
+
+- **`maxSessionTurns`**: (number) The maximum number of turns (user + model
+  exchanges) allowed in a single session. Set to `-1` for unlimited (default).
+
+  **Behavior when limit is reached:**
+  - **Interactive Mode:** The CLI shows an informational message and stops
+    sending requests to the model. You must manually start a new session.
+  - **Non-Interactive Mode:** The CLI exits with an error.

package/dist/docs/cli/settings.md

@@ -0,0 +1,139 @@
+# Gemini CLI settings (`/settings` command)
+
+Control your Gemini CLI experience with the `/settings` command. The `/settings`
+command opens a dialog to view and edit all your Gemini CLI settings, including
+your UI experience, keybindings, and accessibility features.
+
+Your Gemini CLI settings are stored in a `settings.json` file. In addition to
+using the `/settings` command, you can also edit them in one of the following
+locations:
+
+- **User settings**: `~/.gemini/settings.json`
+- **Workspace settings**: `your-project/.gemini/settings.json`
+
+Note: Workspace settings override user settings.
+
+## Settings reference
+
+Here is a list of all the available settings, grouped by category and ordered as
+they appear in the UI.
+
+<!-- SETTINGS-AUTOGEN:START -->
+
+### General
+
+| UI Label                        | Setting                            | Description                                                   | Default |
+| ------------------------------- | ---------------------------------- | ------------------------------------------------------------- | ------- |
+| Preview Features (e.g., models) | `general.previewFeatures`          | Enable preview features (e.g., preview models).               | `false` |
+| Vim Mode                        | `general.vimMode`                  | Enable Vim keybindings                                        | `false` |
+| Enable Auto Update              | `general.enableAutoUpdate`         | Enable automatic updates.                                     | `true`  |
+| Enable Prompt Completion        | `general.enablePromptCompletion`   | Enable AI-powered prompt completion suggestions while typing. | `false` |
+| Debug Keystroke Logging         | `general.debugKeystrokeLogging`    | Enable debug logging of keystrokes to the console.            | `false` |
+| Enable Session Cleanup          | `general.sessionRetention.enabled` | Enable automatic session cleanup                              | `false` |
+
+### Output
+
+| UI Label      | Setting         | Description                                            | Default  |
+| ------------- | --------------- | ------------------------------------------------------ | -------- |
+| Output Format | `output.format` | The format of the CLI output. Can be `text` or `json`. | `"text"` |
+
+### UI
+
+| UI Label                       | Setting                                 | Description                                                                                                                                                       | Default |
+| ------------------------------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| Hide Window Title              | `ui.hideWindowTitle`                    | Hide the window title bar                                                                                                                                         | `false` |
+| Show Thoughts in Title         | `ui.showStatusInTitle`                  | Show Gemini CLI model thoughts in the terminal window title during the working phase                                                                              | `false` |
+| Dynamic Window Title           | `ui.dynamicWindowTitle`                 | Update the terminal window title with current status icons (Ready: ◇, Action Required: ✋, Working: ✦)                                                            | `true`  |
+| Show Home Directory Warning    | `ui.showHomeDirectoryWarning`           | Show a warning when running Gemini CLI in the home directory.                                                                                                     | `true`  |
+| Hide Tips                      | `ui.hideTips`                           | Hide helpful tips in the UI                                                                                                                                       | `false` |
+| Hide Banner                    | `ui.hideBanner`                         | Hide the application banner                                                                                                                                       | `false` |
+| Hide Context Summary           | `ui.hideContextSummary`                 | Hide the context summary (GEMINI.md, MCP servers) above the input.                                                                                                | `false` |
+| Hide CWD                       | `ui.footer.hideCWD`                     | Hide the current working directory path in the footer.                                                                                                            | `false` |
+| Hide Sandbox Status            | `ui.footer.hideSandboxStatus`           | Hide the sandbox status indicator in the footer.                                                                                                                  | `false` |
+| Hide Model Info                | `ui.footer.hideModelInfo`               | Hide the model name and context usage in the footer.                                                                                                              | `false` |
+| Hide Context Window Percentage | `ui.footer.hideContextPercentage`       | Hides the context window remaining percentage.                                                                                                                    | `true`  |
+| Hide Footer                    | `ui.hideFooter`                         | Hide the footer from the UI                                                                                                                                       | `false` |
+| Show Memory Usage              | `ui.showMemoryUsage`                    | Display memory usage information in the UI                                                                                                                        | `false` |
+| Show Line Numbers              | `ui.showLineNumbers`                    | Show line numbers in the chat.                                                                                                                                    | `true`  |
+| Show Citations                 | `ui.showCitations`                      | Show citations for generated text in the chat.                                                                                                                    | `false` |
+| Show Model Info In Chat        | `ui.showModelInfoInChat`                | Show the model name in the chat for each model turn.                                                                                                              | `false` |
+| Show User Identity             | `ui.showUserIdentity`                   | Show the logged-in user's identity (e.g. email) in the UI.                                                                                                        | `true`  |
+| Use Alternate Screen Buffer    | `ui.useAlternateBuffer`                 | Use an alternate screen buffer for the UI, preserving shell history.                                                                                              | `false` |
+| Use Background Color           | `ui.useBackgroundColor`                 | Whether to use background colors in the UI.                                                                                                                       | `true`  |
+| Incremental Rendering          | `ui.incrementalRendering`               | Enable incremental rendering for the UI. This option will reduce flickering but may cause rendering artifacts. Only supported when useAlternateBuffer is enabled. | `true`  |
+| Show Spinner                   | `ui.showSpinner`                        | Show the spinner during operations.                                                                                                                               | `true`  |
+| Enable Loading Phrases         | `ui.accessibility.enableLoadingPhrases` | Enable loading phrases during operations.                                                                                                                         | `true`  |
+| Screen Reader Mode             | `ui.accessibility.screenReader`         | Render output in plain-text to be more screen reader accessible                                                                                                   | `false` |
+
+### IDE
+
+| UI Label | Setting       | Description                  | Default |
+| -------- | ------------- | ---------------------------- | ------- |
+| IDE Mode | `ide.enabled` | Enable IDE integration mode. | `false` |
+
+### Model
+
+| UI Label                | Setting                      | Description                                                                            | Default |
+| ----------------------- | ---------------------------- | -------------------------------------------------------------------------------------- | ------- |
+| Max Session Turns       | `model.maxSessionTurns`      | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.      | `-1`    |
+| Compression Threshold   | `model.compressionThreshold` | The fraction of context usage at which to trigger context compression (e.g. 0.2, 0.3). | `0.5`   |
+| Skip Next Speaker Check | `model.skipNextSpeakerCheck` | Skip the next speaker check.                                                           | `true`  |
+
+### Context
+
+| UI Label                             | Setting                                           | Description                                                                                                                                                                                                                                 | Default |
+| ------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| Memory Discovery Max Dirs            | `context.discoveryMaxDirs`                        | Maximum number of directories to search for memory.                                                                                                                                                                                         | `200`   |
+| Load Memory From Include Directories | `context.loadMemoryFromIncludeDirectories`        | Controls how /memory refresh loads GEMINI.md files. When true, include directories are scanned; when false, only the current directory is used.                                                                                             | `false` |
+| Respect .gitignore                   | `context.fileFiltering.respectGitIgnore`          | Respect .gitignore files when searching.                                                                                                                                                                                                    | `true`  |
+| Respect .geminiignore                | `context.fileFiltering.respectGeminiIgnore`       | Respect .geminiignore files when searching.                                                                                                                                                                                                 | `true`  |
+| Enable Recursive File Search         | `context.fileFiltering.enableRecursiveFileSearch` | Enable recursive file search functionality when completing @ references in the prompt.                                                                                                                                                      | `true`  |
+| Enable Fuzzy Search                  | `context.fileFiltering.enableFuzzySearch`         | Enable fuzzy search when searching for files.                                                                                                                                                                                               | `true`  |
+| Custom Ignore File Paths             | `context.fileFiltering.customIgnoreFilePaths`     | Additional ignore file paths to respect. These files take precedence over .geminiignore and .gitignore. Files earlier in the array take precedence over files later in the array, e.g. the first file takes precedence over the second one. | `[]`    |
+
+### Tools
+
+| UI Label                         | Setting                              | Description                                                                                                                                                                    | Default     |
+| -------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
+| Enable Interactive Shell         | `tools.shell.enableInteractiveShell` | Use node-pty for an interactive shell experience. Fallback to child_process still applies.                                                                                     | `true`      |
+| Show Color                       | `tools.shell.showColor`              | Show color in shell output.                                                                                                                                                    | `false`     |
+| Auto Accept                      | `tools.autoAccept`                   | Automatically accept and execute tool calls that are considered safe (e.g., read-only operations).                                                                             | `false`     |
+| Approval Mode                    | `tools.approvalMode`                 | The default approval mode for tool execution. 'default' prompts for approval, 'auto_edit' auto-approves edit tools, and 'plan' is read-only mode. 'yolo' is not supported yet. | `"default"` |
+| Use Ripgrep                      | `tools.useRipgrep`                   | Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance.                                                                | `true`      |
+| Enable Tool Output Truncation    | `tools.enableToolOutputTruncation`   | Enable truncation of large tool outputs.                                                                                                                                       | `true`      |
+| Tool Output Truncation Threshold | `tools.truncateToolOutputThreshold`  | Truncate tool output if it is larger than this many characters. Set to -1 to disable.                                                                                          | `4000000`   |
+| Tool Output Truncation Lines     | `tools.truncateToolOutputLines`      | The number of lines to keep when truncating tool output.                                                                                                                       | `1000`      |
+| Disable LLM Correction           | `tools.disableLLMCorrection`         | Disable LLM-based error correction for edit tools. When enabled, tools will fail immediately if exact string matches are not found, instead of attempting to self-correct.     | `true`      |
+
+### Security
+
+| UI Label                              | Setting                                         | Description                                                                                                                                                             | Default |
+| ------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| Disable YOLO Mode                     | `security.disableYoloMode`                      | Disable YOLO mode, even if enabled by a flag.                                                                                                                           | `false` |
+| Allow Permanent Tool Approval         | `security.enablePermanentToolApproval`          | Enable the "Allow for all future sessions" option in tool confirmation dialogs.                                                                                         | `false` |
+| Blocks extensions from Git            | `security.blockGitExtensions`                   | Blocks installing and loading extensions from Git.                                                                                                                      | `false` |
+| Extension Source Regex Allowlist      | `security.allowedExtensions`                    | List of Regex patterns for allowed extensions. If nonempty, only extensions that match the patterns in this list are allowed. Overrides the blockGitExtensions setting. | `[]`    |
+| Folder Trust                          | `security.folderTrust.enabled`                  | Setting to track whether Folder trust is enabled.                                                                                                                       | `false` |
+| Enable Environment Variable Redaction | `security.environmentVariableRedaction.enabled` | Enable redaction of environment variables that may contain secrets.                                                                                                     | `false` |
+
+### Experimental
+
+| UI Label         | Setting                      | Description                                                                         | Default |
+| ---------------- | ---------------------------- | ----------------------------------------------------------------------------------- | ------- |
+| Use OSC 52 Paste | `experimental.useOSC52Paste` | Use OSC 52 sequence for pasting instead of clipboardy (useful for remote sessions). | `false` |
+| Plan             | `experimental.plan`          | Enable planning features (Plan Mode and tools).                                     | `false` |
+
+### Skills
+
+| UI Label            | Setting          | Description          | Default |
+| ------------------- | ---------------- | -------------------- | ------- |
+| Enable Agent Skills | `skills.enabled` | Enable Agent Skills. | `true`  |
+
+### HooksConfig
+
+| UI Label           | Setting                     | Description                                                                      | Default |
+| ------------------ | --------------------------- | -------------------------------------------------------------------------------- | ------- |
+| Enable Hooks       | `hooksConfig.enabled`       | Canonical toggle for the hooks system. When disabled, no hooks will be executed. | `true`  |
+| Hook Notifications | `hooksConfig.notifications` | Show visual indicators when hooks are executing.                                 | `true`  |
+
+<!-- SETTINGS-AUTOGEN:END -->

package/dist/docs/cli/skills.md

@@ -0,0 +1,112 @@
+# Agent Skills
+
+Agent Skills allow you to extend Gemini CLI with specialized expertise,
+procedural workflows, and task-specific resources. Based on the
+[Agent Skills](https://agentskills.io) open standard, a "skill" is a
+self-contained directory that packages instructions and assets into a
+discoverable capability.
+
+## Overview
+
+Unlike general context files ([`GEMINI.md`](./gemini-md.md)), which provide
+persistent workspace-wide background, Skills represent **on-demand expertise**.
+This allows Gemini to maintain a vast library of specialized capabilities—such
+as security auditing, cloud deployments, or codebase migrations—without
+cluttering the model's immediate context window.
+
+Gemini autonomously decides when to employ a skill based on your request and the
+skill's description. When a relevant skill is identified, the model "pulls in"
+the full instructions and resources required to complete the task using the
+`activate_skill` tool.
+
+## Key Benefits
+
+- **Shared Expertise:** Package complex workflows (like a specific team's PR
+  review process) into a folder that anyone can use.
+- **Repeatable Workflows:** Ensure complex multi-step tasks are performed
+  consistently by providing a procedural framework.
+- **Resource Bundling:** Include scripts, templates, or example data alongside
+  instructions so the agent has everything it needs.
+- **Progressive Disclosure:** Only skill metadata (name and description) is
+  loaded initially. Detailed instructions and resources are only disclosed when
+  the model explicitly activates the skill, saving context tokens.
+
+## Skill Discovery Tiers
+
+Gemini CLI discovers skills from three primary locations:
+
+1.  **Workspace Skills** (`.gemini/skills/`): Workspace-specific skills that are
+    typically committed to version control and shared with the team.
+2.  **User Skills** (`~/.gemini/skills/`): Personal skills available across all
+    your workspaces.
+3.  **Extension Skills**: Skills bundled within installed
+    [extensions](../extensions/index.md).
+
+**Precedence:** If multiple skills share the same name, higher-precedence
+locations override lower ones: **Workspace > User > Extension**.
+
+## Managing Skills
+
+### In an Interactive Session
+
+Use the `/skills` slash command to view and manage available expertise:
+
+- `/skills list` (default): Shows all discovered skills and their status.
+- `/skills disable <name>`: Prevents a specific skill from being used.
+- `/skills enable <name>`: Re-enables a disabled skill.
+- `/skills reload`: Refreshes the list of discovered skills from all tiers.
+
+_Note: `/skills disable` and `/skills enable` default to the `user` scope. Use
+`--scope workspace` to manage workspace-specific settings._
+
+### From the Terminal
+
+The `gemini skills` command provides management utilities:
+
+```bash
+# List all discovered skills
+gemini skills list
+
+# Install a skill from a Git repository, local directory, or zipped skill file (.skill)
+# Uses the user scope by default (~/.gemini/skills)
+gemini skills install https://github.com/user/repo.git
+gemini skills install /path/to/local/skill
+gemini skills install /path/to/local/my-expertise.skill
+
+# Install a specific skill from a monorepo or subdirectory using --path
+gemini skills install https://github.com/my-org/my-skills.git --path skills/frontend-design
+
+# Install to the workspace scope (.gemini/skills)
+gemini skills install /path/to/skill --scope workspace
+
+# Uninstall a skill by name
+gemini skills uninstall my-expertise --scope workspace
+
+# Enable a skill (globally)
+gemini skills enable my-expertise
+
+# Disable a skill. Can use --scope to specify workspace or user (defaults to workspace)
+gemini skills disable my-expertise --scope workspace
+```
+
+## How it Works (Security & Privacy)
+
+1.  **Discovery**: At the start of a session, Gemini CLI scans the discovery
+    tiers and injects the name and description of all enabled skills into the
+    system prompt.
+2.  **Activation**: When Gemini identifies a task matching a skill's
+    description, it calls the `activate_skill` tool.
+3.  **Consent**: You will see a confirmation prompt in the UI detailing the
+    skill's name, purpose, and the directory path it will gain access to.
+4.  **Injection**: Upon your approval:
+    - The `SKILL.md` body and folder structure is added to the conversation
+      history.
+    - The skill's directory is added to the agent's allowed file paths, granting
+      it permission to read any bundled assets.
+5.  **Execution**: The model proceeds with the specialized expertise active. It
+    is instructed to prioritize the skill's procedural guidance within reason.
+
+## Creating your own skills
+
+To create your own skills, see the [Create Agent Skills](./creating-skills.md)
+guide.

package/dist/docs/cli/system-prompt.md

@@ -0,0 +1,125 @@
+# System Prompt Override (GEMINI_SYSTEM_MD)
+
+The core system instructions that guide Gemini CLI can be completely replaced
+with your own Markdown file. This feature is controlled via the
+`GEMINI_SYSTEM_MD` environment variable.
+
+## Overview
+
+The `GEMINI_SYSTEM_MD` variable instructs the CLI to use an external Markdown
+file for its system prompt, completely overriding the built-in default. This is
+a full replacement, not a merge. If you use a custom file, none of the original
+core instructions will apply unless you include them yourself.
+
+This feature is intended for advanced users who need to enforce strict,
+project-specific behavior or create a customized persona.
+
+> Tip: You can export the current default system prompt to a file first, review
+> it, and then selectively modify or replace it (see
+> [“Export the default prompt”](#export-the-default-prompt-recommended)).
+
+## How to enable
+
+You can set the environment variable temporarily in your shell, or persist it
+via a `.gemini/.env` file. See
+[Persisting Environment Variables](../get-started/authentication.md#persisting-environment-variables).
+
+- Use the project default path (`.gemini/system.md`):
+  - `GEMINI_SYSTEM_MD=true` or `GEMINI_SYSTEM_MD=1`
+  - The CLI reads `./.gemini/system.md` (relative to your current project
+    directory).
+
+- Use a custom file path:
+  - `GEMINI_SYSTEM_MD=/absolute/path/to/my-system.md`
+  - Relative paths are supported and resolved from the current working
+    directory.
+  - Tilde expansion is supported (e.g., `~/my-system.md`).
+
+- Disable the override (use built‑in prompt):
+  - `GEMINI_SYSTEM_MD=false` or `GEMINI_SYSTEM_MD=0` or unset the variable.
+
+If the override is enabled but the target file does not exist, the CLI will
+error with: `missing system prompt file '<path>'`.
+
+## Quick examples
+
+- One‑off session using a project file:
+  - `GEMINI_SYSTEM_MD=1 gemini`
+- Persist for a project using `.gemini/.env`:
+  - Create `.gemini/system.md`, then add to `.gemini/.env`:
+    - `GEMINI_SYSTEM_MD=1`
+- Use a custom file under your home directory:
+  - `GEMINI_SYSTEM_MD=~/prompts/SYSTEM.md gemini`
+
+## UI indicator
+
+When `GEMINI_SYSTEM_MD` is active, the CLI shows a `|⌐■_■|` indicator in the UI
+to signal custom system‑prompt mode.
+
+## Variable Substitution
+
+When using a custom system prompt file, you can use the following variables to
+dynamically include built-in content:
+
+- `${AgentSkills}`: Injects a complete section (including header) of all
+  available agent skills.
+- `${SubAgents}`: Injects a complete section (including header) of available
+  sub-agents.
+- `${AvailableTools}`: Injects a bulleted list of all currently enabled tool
+  names.
+- Tool Name Variables: Injects the actual name of a tool using the pattern:
+  `${toolName}_ToolName` (e.g., `${write_file_ToolName}`,
+  `${run_shell_command_ToolName}`).
+
+  This pattern is generated dynamically for all available tools.
+
+### Example
+
+```markdown
+# Custom System Prompt
+
+You are a helpful assistant. ${AgentSkills}
+${SubAgents}
+
+## Tooling
+
+The following tools are available to you: ${AvailableTools}
+
+You can use ${write_file_ToolName} to save logs.
+```
+
+## Export the default prompt (recommended)
+
+Before overriding, export the current default prompt so you can review required
+safety and workflow rules.
+
+- Write the built‑in prompt to the project default path:
+  - `GEMINI_WRITE_SYSTEM_MD=1 gemini`
+- Or write to a custom path:
+  - `GEMINI_WRITE_SYSTEM_MD=~/prompts/DEFAULT_SYSTEM.md gemini`
+
+This creates the file and writes the current built‑in system prompt to it.
+
+## Best practices: SYSTEM.md vs GEMINI.md
+
+- SYSTEM.md (firmware):
+  - Non‑negotiable operational rules: safety, tool‑use protocols, approvals, and
+    mechanics that keep the CLI reliable.
+  - Stable across tasks and projects (or per project when needed).
+- GEMINI.md (strategy):
+  - Persona, goals, methodologies, and project/domain context.
+  - Evolves per task; relies on SYSTEM.md for safe execution.
+
+Keep SYSTEM.md minimal but complete for safety and tool operation. Keep
+GEMINI.md focused on high‑level guidance and project specifics.
+
+## Troubleshooting
+
+- Error: `missing system prompt file '…'`
+  - Ensure the referenced path exists and is readable.
+  - For `GEMINI_SYSTEM_MD=1|true`, create `./.gemini/system.md` in your project.
+- Override not taking effect
+  - Confirm the variable is loaded (use `.gemini/.env` or export in your shell).
+  - Paths are resolved from the current working directory; try an absolute path.
+- Restore defaults
+  - Unset `GEMINI_SYSTEM_MD` or set it to `0`/`false`.