@maincode-ai/matilda-code 0.21.13 → 0.22.0-nightly.20261101.b0ad315a4

package/bundled/mainy/docs/features/memory.md

@@ -1,185 +0,0 @@
-# Memory
-
-Every Matilda Code session starts with a fresh context window. Two mechanisms carry knowledge across sessions so you don't have to re-explain yourself every time:
-
-- **MATILDA.md** — instructions _you_ write once and Matilda reads every session
-- **Auto-memory** — notes Matilda writes itself based on what it learns from you
-
----
-
-## MATILDA.md: your instructions to Matilda
-
-MATILDA.md is a plain text file where you write things Matilda should always know about your project or your preferences. Think of it as a permanent briefing that loads at the start of every conversation.
-
-### What to put in MATILDA.md
-
-Add things you'd otherwise have to repeat every session:
-
-- Build and test commands (`npm run test`, `make build`)
-- Coding conventions your team follows ("all new files must have JSDoc comments")
-- Architectural decisions ("we use the repository pattern, never call the database directly from controllers")
-- Personal preferences ("always use pnpm, not npm")
-
-Don't include things Matilda can figure out by reading your code. MATILDA.md works best when it's short and specific — the longer it gets, the less reliably Matilda follows it.
-
-### Where to create MATILDA.md
-
-| File                             | Who it applies to                                |
-| -------------------------------- | ------------------------------------------------ |
-| `~/.matilda/MATILDA.md`          | You, across all your projects                    |
-| `MATILDA.md` in the project root | Your whole team (commit it to source control)    |
-| `.matilda/MATILDA.local.md`      | Only you, only in this project (keep out of git) |
-
-You can have any combination of these. Matilda loads all of them when you start a session.
-
-If your repository already has an `AGENTS.md` file for other AI tools, Matilda reads that too. No need to duplicate instructions.
-
-#### When to use `.matilda/MATILDA.local.md`
-
-Use it for **project-specific but personal** instructions — things that belong to this project but shouldn't be shared with the team:
-
-- Your own cluster ID, container registry namespace, or cloud account
-- A personal debug command that hardcodes your local environment
-- Notes you want Matilda to know about your work-in-progress, but not commit
-
-It loads **after** the shared project `MATILDA.md`, so your local instructions can supplement or override the team's.
-
-**You must gitignore it yourself.** Although `.matilda/` is often treated as a local directory, matilda-code does not generate a `.gitignore` for you, and some projects commit `.matilda/settings.json`. Add this line to your `.gitignore` (or to your global git ignore):
-
-```
-.matilda/MATILDA.local.md
-```
-
-### Generate one automatically with `/init`
-
-Run `/init` and Matilda will analyze your codebase to create a starter MATILDA.md with build commands, test instructions, and conventions it finds. If one already exists, it suggests additions instead of overwriting.
-
-### Reference other files
-
-You can point MATILDA.md at other files so Matilda reads them too:
-
-```markdown
-See @README.md for project overview.
-
-# Conventions
-
-- Git workflow: @docs/git-workflow.md
-```
-
-Use `@path/to/file` anywhere in MATILDA.md. Relative paths resolve from the MATILDA.md file itself.
-
----
-
-## Auto-memory: what Matilda learns about you
-
-Auto-memory runs in the background. After each of your conversations, Matilda quietly saves useful things it learned — your preferences, feedback you gave, project context — so it can use them in future sessions without you repeating yourself.
-
-This is different from MATILDA.md: you don't write it, Matilda does.
-
-### What Matilda saves
-
-Matilda looks for four kinds of things worth remembering:
-
-| What                    | Examples                                                 |
-| ----------------------- | -------------------------------------------------------- |
-| **About you**           | Your role, background, how you like to work              |
-| **Your feedback**       | Corrections you made, approaches you confirmed           |
-| **Project context**     | Ongoing work, decisions, goals not obvious from the code |
-| **External references** | Dashboards, ticket trackers, docs links you mentioned    |
-
-Matilda doesn't save everything — only things that would actually be useful next time.
-
-### Where it's stored
-
-Auto-memory files live at `~/.matilda/projects/<project>/memory/`. All branches and worktrees of the same repository share the same memory folder, so what Matilda learns in one branch is available in others.
-
-Everything saved is plain markdown — you can open, edit, or delete any file at any time.
-
-### Periodic cleanup
-
-Matilda periodically goes through its saved memories to remove duplicates and clean up outdated entries. This runs automatically in the background once a day after enough sessions have accumulated. You can trigger it manually with `/dream` if you want it to run now.
-
-While cleanup is running, **✦ dreaming** appears in the corner of the screen. Your session continues normally.
-
-### Turning it on or off
-
-Auto-memory is on by default. To toggle it, open `/memory` and use the switches at the top. You can turn off just the automatic saving, just the periodic cleanup, or both.
-
-You can also set them in `~/.matilda/settings.json` (applies to all projects) or `.matilda/settings.json` (this project only):
-
-```json
-{
-  "memory": {
-    "enableManagedAutoMemory": true,
-    "enableManagedAutoDream": true
-  }
-}
-```
-
----
-
-## Commands
-
-### `/memory`
-
-Opens the Memory panel. From here you can:
-
-- Turn auto-memory saving on or off
-- Turn periodic cleanup (dream) on or off
-- Open your personal MATILDA.md (`~/.matilda/MATILDA.md`)
-- Open the project MATILDA.md
-- Browse the auto-memory folder
-
-### `/init`
-
-Generates a starter MATILDA.md for your project. Matilda reads your codebase and fills in build commands, test instructions, and conventions it discovers.
-
-### `/remember <text>`
-
-Immediately saves something to auto-memory without waiting for Matilda to pick it up automatically:
-
-```
-/remember always use snake_case for Python variable names
-/remember the staging environment is at staging.example.com
-```
-
-### `/forget <text>`
-
-Removes auto-memory entries that match your description:
-
-```
-/forget old workaround for the login bug
-```
-
-### `/dream`
-
-Runs the memory cleanup now instead of waiting for the automatic schedule:
-
-```
-/dream
-```
-
----
-
-## Troubleshooting
-
-### Matilda isn't following my MATILDA.md
-
-Open `/memory` to see which files are loaded. If your file isn't listed, Matilda can't see it — make sure it's in the project root or `~/.matilda/`.
-
-Instructions work better when they're specific:
-
-- ✓ `Use 2-space indentation for TypeScript files`
-- ✗ `Format code nicely`
-
-If you have multiple MATILDA.md files with conflicting instructions, Matilda may behave inconsistently. Review them and remove any contradictions.
-
-### I want to see what Matilda has saved
-
-Run `/memory` and select **Open auto-memory folder**. All saved memories are readable markdown files you can browse, edit, or delete.
-
-### Matilda keeps forgetting things
-
-If auto-memory is on but Matilda doesn't seem to remember things across sessions, try running `/dream` to force a cleanup pass. Also check `/memory` to confirm both toggles are enabled.
-
-For things you always want Matilda to remember, add them to MATILDA.md instead — auto-memory is best-effort, MATILDA.md is guaranteed.

package/bundled/mainy/docs/features/sandbox.md

@@ -1,249 +0,0 @@
-# Sandbox
-
-This document explains how to run Matilda Code inside a sandbox to reduce risk when tools execute shell commands or modify files.
-
-## Prerequisites
-
-Before using sandboxing, you need to install and set up Matilda Code:
-
-```bash
-npm install -g @maincode-ai/matilda-code
-```
-
-To verify the installation
-
-```bash
-matilda --version
-```
-
-## Overview of sandboxing
-
-Sandboxing isolates potentially dangerous operations (such as shell commands or file modifications) from your host system, providing a security barrier between the CLI and your environment.
-
-The benefits of sandboxing include:
-
-- **Security**: Prevent accidental system damage or data loss.
-- **Isolation**: Limit file system access to project directory.
-- **Consistency**: Ensure reproducible environments across different systems.
-- **Safety**: Reduce risk when working with untrusted code or experimental commands.
-
-> [!note]
->
-> **Naming note:** Some sandbox-related environment variables may have used the `GEMINI_*` prefix historically. All new environment variables use the `MATILDA_*` prefix.
-
-## Sandboxing methods
-
-Your ideal method of sandboxing may differ depending on your platform and your preferred container solution.
-
-### 1. macOS Seatbelt (macOS only)
-
-Lightweight, built-in sandboxing using `sandbox-exec`.
-
-**Default profile**: `permissive-open` - restricts writes outside the project directory, but allows most other operations and outbound network access.
-
-**Best for**: Fast, no Docker required, strong guardrails for file writes.
-
-### 2. Container-based (Docker/Podman)
-
-Cross-platform sandboxing with complete process isolation.
-
-By default, Matilda Code uses a published sandbox image (configured in the CLI package) and will pull it as needed.
-
-The container sandbox mounts your workspace and your `~/.matilda` directory into the container so auth and settings persist between runs.
-
-**Best for**: Strong isolation on any OS, consistent tooling inside a known image.
-
-### Choosing a method
-
-- **On macOS**:
-  - Use Seatbelt when you want lightweight sandboxing (recommended for most users).
-  - Use Docker/Podman when you need a full Linux userland (e.g., tools that require Linux binaries).
-- **On Linux/Windows**:
-  - Use Docker or Podman.
-
-## Quickstart
-
-```bash
-# Enable sandboxing with command flag
-matilda -s -p "analyze the code structure"
-
-# Or enable sandboxing for your shell session (recommended for CI / scripts)
-export MATILDA_SANDBOX=true   # true auto-picks a provider (see notes below)
-matilda -p "run the test suite"
-
-# Configure in settings.json
-{
-  "tools": {
-    "sandbox": true
-  }
-}
-```
-
-> [!tip]
->
-> **Provider selection notes:**
->
-> - On **macOS**, `MATILDA_SANDBOX=true` typically selects `sandbox-exec` (Seatbelt) if available.
-> - On **Linux/Windows**, `MATILDA_SANDBOX=true` requires `docker` or `podman` to be installed.
-> - To force a provider, set `MATILDA_SANDBOX=docker|podman|sandbox-exec`.
-
-## Configuration
-
-### Enable sandboxing (in order of precedence)
-
-1. **Environment variable**: `MATILDA_SANDBOX=true|false|docker|podman|sandbox-exec`
-2. **Command flag / argument**: `-s`, `--sandbox`, or `--sandbox=<provider>`
-3. **Settings file**: `tools.sandbox` in your `settings.json` (e.g., `{"tools": {"sandbox": true}}`).
-
-> [!important]
->
-> If `MATILDA_SANDBOX` is set, it **overrides** the CLI flag and `settings.json`.
-
-### Configure the sandbox image (Docker/Podman)
-
-- **CLI flag**: `--sandbox-image <image>`
-- **Environment variable**: `MATILDA_SANDBOX_IMAGE=<image>`
-- **Settings file**: `tools.sandboxImage` in your `settings.json` (e.g., `{"tools": {"sandboxImage": "ghcr.io/maincode/matilda-code:0.14.1"}}`)
-
-Priority order (highest to lowest):
-
-1. `--sandbox-image`
-2. `MATILDA_SANDBOX_IMAGE`
-3. `tools.sandboxImage`
-4. Built-in default image from the CLI package (for example `ghcr.io/maincode/matilda-code:<version>`)
-
-`settings.env.MATILDA_SANDBOX_IMAGE` also works as a generic env injection mechanism, but `tools.sandboxImage` is the preferred persistent setting.
-
-### macOS Seatbelt profiles
-
-Built-in profiles (set via `SEATBELT_PROFILE` env var):
-
-- `permissive-open` (default): Write restrictions, network allowed
-- `permissive-closed`: Write restrictions, no network
-- `permissive-proxied`: Write restrictions, network via proxy
-- `restrictive-open`: Strict restrictions, network allowed
-- `restrictive-closed`: Maximum restrictions
-- `restrictive-proxied`: Strict restrictions, network via proxy
-
-> [!tip]
->
-> Start with `permissive-open`, then tighten to `restrictive-closed` if your workflow still works.
-
-### Custom Seatbelt profiles (macOS)
-
-To use a custom Seatbelt profile:
-
-1. Create a file named `.matilda/sandbox-macos-<profile_name>.sb` in your project.
-2. Set `SEATBELT_PROFILE=<profile_name>`.
-
-### Custom Sandbox Flags
-
-For container-based sandboxing, you can inject custom flags into the `docker` or `podman` command using the `SANDBOX_FLAGS` environment variable. This is useful for advanced configurations, such as disabling security features for specific use cases.
-
-**Example (Podman)**:
-
-To disable SELinux labeling for volume mounts, you can set the following:
-
-```bash
-export SANDBOX_FLAGS="--security-opt label=disable"
-```
-
-Multiple flags can be provided as a space-separated string:
-
-```bash
-export SANDBOX_FLAGS="--flag1 --flag2=value"
-```
-
-### Network proxying (all sandbox methods)
-
-If you want to restrict outbound network access to an allowlist, you can run a local proxy alongside the sandbox:
-
-- Set `MATILDA_SANDBOX_PROXY_COMMAND=<command>`
-- The command must start a proxy server that listens on `:::8877`
-
-This is especially useful with `*-proxied` Seatbelt profiles.
-
-For a working allowlist-style proxy example, see: [Example Proxy Script](/developers/examples/proxy-script).
-
-## Linux UID/GID handling
-
-On Linux, Matilda Code defaults to enabling UID/GID mapping so the sandbox runs as your user (and reuses the mounted `~/.matilda`). Override with:
-
-```bash
-export SANDBOX_SET_UID_GID=true   # Force host UID/GID
-export SANDBOX_SET_UID_GID=false  # Disable UID/GID mapping
-```
-
-## Troubleshooting
-
-### Common issues
-
-**"Operation not permitted"**
-
-- Operation requires access outside sandbox.
-- On macOS Seatbelt: try a more permissive `SEATBELT_PROFILE`.
-- On Docker/Podman: verify the workspace is mounted and your command doesn’t require access outside the project directory.
-
-**Missing commands**
-
-- Container sandbox: add them via `.matilda/sandbox.Dockerfile` or `.matilda/sandbox.bashrc`.
-- Seatbelt: your host binaries are used, but the sandbox may restrict access to some paths.
-
-**Java not available in Docker sandbox**
-
-The official Matilda Code Docker image is intentionally minimal to keep the image small, secure, and fast to pull. Different users require different language runtimes (Java, Python, Node.js, etc.), and bundling all environments into a single image is not practical. Therefore, Java is **not included by default** in the Docker sandbox.
-
-If your workflow requires Java, you can extend the base image by creating a `.matilda/sandbox.Dockerfile` in your project:
-
-```dockerfile
-FROM ghcr.io/maincode/matilda-code:latest
-
-RUN apt-get update && \
-    apt-get install -y openjdk-17-jre && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
-```
-
-Then rebuild the sandbox image:
-
-```bash
-MATILDA_SANDBOX=docker BUILD_SANDBOX=1 matilda -s
-```
-
-For more details on customizing the sandbox, see [Customizing the sandbox environment](/developers/tools/sandbox).
-
-**Network issues**
-
-- Check sandbox profile allows network.
-- Verify proxy configuration.
-
-### Debug mode
-
-```bash
-DEBUG=1 matilda -s -p "debug command"
-```
-
-**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect the CLI due to automatic exclusion. Use `.matilda/.env` files for Matilda Code-specific debug settings.
-
-### Inspect sandbox
-
-```bash
-# Check environment
-matilda -s -p "run shell command: env | grep SANDBOX"
-
-# List mounts
-matilda -s -p "run shell command: mount | grep workspace"
-```
-
-## Security notes
-
-- Sandboxing reduces but doesn't eliminate all risks.
-- Use the most restrictive profile that allows your work.
-- Container overhead is minimal after the first pull/build.
-- GUI applications may not work in sandboxes.
-
-## Related documentation
-
-- [Configuration](../configuration/settings): Full configuration options.
-- [Commands](../features/commands): Available commands.
-- [Troubleshooting](../support/troubleshooting): General troubleshooting.

package/bundled/mainy/docs/features/scheduled-tasks.md

@@ -1,139 +0,0 @@
-# Run Prompts on a Schedule
-
-> Use `/loop` and the cron scheduling tools to run prompts repeatedly, poll for status, or set one-time reminders within a Matilda Code session.
-
-Scheduled tasks let Matilda Code re-run a prompt automatically on an interval. Use them to poll a deployment, babysit a PR, check back on a long-running build, or remind yourself to do something later in the session.
-
-Tasks are session-scoped: they live in the current Matilda Code process and are gone when you exit. Nothing is written to disk.
-
-> **Tip:** Scheduled tasks are enabled by default. To disable them, set `experimental.cron: false` in your [settings](../configuration/settings.md), or set `MATILDA_CODE_DISABLE_CRON=1` in your environment.
-
-## Schedule a recurring prompt with /loop
-
-The `/loop` [bundled skill](skills.md) is the quickest way to schedule a recurring prompt. Pass an optional interval and a prompt, and Matilda Code sets up a cron job that fires in the background while the session stays open.
-
-```text
-/loop 5m check if the deployment finished and tell me what happened
-```
-
-Matilda Code parses the interval, converts it to a cron expression, schedules the job, and confirms the cadence and job ID. It then immediately executes the prompt once — you don't have to wait for the first cron fire.
-
-### Interval syntax
-
-Intervals are optional. You can lead with them, trail with them, or leave them out entirely.
-
-| Form                    | Example                               | Parsed interval              |
-| :---------------------- | :------------------------------------ | :--------------------------- |
-| Leading token           | `/loop 30m check the build`           | every 30 minutes             |
-| Trailing `every` clause | `/loop check the build every 2 hours` | every 2 hours                |
-| No interval             | `/loop check the build`               | defaults to every 10 minutes |
-
-Supported units are `s` for seconds, `m` for minutes, `h` for hours, and `d` for days. Seconds are rounded up to the nearest minute since cron has one-minute granularity. Intervals that don't divide evenly into their unit, such as `7m` or `90m`, are rounded to the nearest clean interval and Matilda Code tells you what it picked.
-
-### Loop over another command
-
-The scheduled prompt can itself be a command or skill invocation. This is useful for re-running a workflow you've already packaged.
-
-```text
-/loop 20m /review-pr 1234
-```
-
-Each time the job fires, Matilda Code runs `/review-pr 1234` as if you had typed it.
-
-### Manage loops
-
-`/loop` also supports two subcommands for managing existing jobs:
-
-```text
-/loop list
-```
-
-Lists all scheduled jobs with their IDs and cron expressions.
-
-```text
-/loop clear
-```
-
-Cancels all scheduled jobs at once.
-
-## Set a one-time reminder
-
-For one-shot reminders, describe what you want in natural language instead of using `/loop`. Matilda Code schedules a single-fire task that deletes itself after running.
-
-```text
-remind me at 3pm to push the release branch
-```
-
-```text
-in 45 minutes, check whether the integration tests passed
-```
-
-Matilda Code pins the fire time to a specific minute and hour using a cron expression and confirms when it will fire.
-
-## Manage scheduled tasks
-
-Ask Matilda Code in natural language to list or cancel tasks, or reference the underlying tools directly.
-
-```text
-what scheduled tasks do I have?
-```
-
-```text
-cancel the deploy check job
-```
-
-Under the hood, Matilda Code uses these tools:
-
-| Tool         | Purpose                                                                                                         |
-| :----------- | :-------------------------------------------------------------------------------------------------------------- |
-| `CronCreate` | Schedule a new task. Accepts a 5-field cron expression, the prompt to run, and whether it recurs or fires once. |
-| `CronList`   | List all scheduled tasks with their IDs, schedules, and prompts.                                                |
-| `CronDelete` | Cancel a task by ID.                                                                                            |
-
-Each scheduled task has an 8-character ID you can pass to `CronDelete`. A session can hold up to 50 scheduled tasks at once.
-
-## How scheduled tasks run
-
-The scheduler checks every second for due tasks and enqueues them when the session is idle. A scheduled prompt fires between your turns, not while Matilda Code is mid-response. If Matilda Code is busy when a task comes due, the prompt waits until the current turn ends.
-
-All times are interpreted in your local timezone. A cron expression like `0 9 * * *` means 9am wherever you're running Matilda Code, not UTC.
-
-### Jitter
-
-To avoid every session hitting the API at the same wall-clock moment, the scheduler adds a small deterministic offset to fire times:
-
-- **Recurring tasks** fire up to 10% of their period late, capped at 15 minutes. An hourly job might fire anywhere from `:00` to `:06`.
-- **One-shot tasks** scheduled for the top or bottom of the hour (minute `:00` or `:30`) fire up to 90 seconds early.
-
-The offset is derived from the task ID, so the same task always gets the same offset. If exact timing matters, pick a minute that is not `:00` or `:30`, for example `3 9 * * *` instead of `0 9 * * *`, and the one-shot jitter will not apply.
-
-### Three-day expiry
-
-Recurring tasks automatically expire 3 days after creation. The task fires one final time, then deletes itself. This bounds how long a forgotten loop can run. If you need a recurring task to last longer, cancel and recreate it before it expires.
-
-One-shot tasks do not expire on a timer — they simply delete themselves after firing once.
-
-## Cron expression reference
-
-`CronCreate` accepts standard 5-field cron expressions: `minute hour day-of-month month day-of-week`. All fields support wildcards (`*`), single values (`5`), steps (`*/15`), ranges (`1-5`), and comma-separated lists (`1,15,30`).
-
-| Example        | Meaning                      |
-| :------------- | :--------------------------- |
-| `*/5 * * * *`  | Every 5 minutes              |
-| `0 * * * *`    | Every hour on the hour       |
-| `7 * * * *`    | Every hour at 7 minutes past |
-| `0 9 * * *`    | Every day at 9am local       |
-| `0 9 * * 1-5`  | Weekdays at 9am local        |
-| `30 14 15 3 *` | March 15 at 2:30pm local     |
-
-Day-of-week uses `0` or `7` for Sunday through `6` for Saturday. When both day-of-month and day-of-week are constrained (neither is `*`), a date matches if either field matches — this follows standard vixie-cron semantics.
-
-Extended syntax like `L`, `W`, `?`, and name aliases such as `MON` or `JAN` is not supported.
-
-## Limitations
-
-Session-scoped scheduling has inherent constraints:
-
-- Tasks only fire while Matilda Code is running and idle. Closing the terminal or letting the session exit cancels everything.
-- No catch-up for missed fires. If a task's scheduled time passes while Matilda Code is busy on a long-running request, it fires once when Matilda Code becomes idle, not once per missed interval.
-- No persistence across restarts. Restarting Matilda Code clears all session-scoped tasks.