# Built-in Resource Types

CleverAgents ships with several built-in resource types that cover common
filesystem and version-control workflows. Built-in types use simple
unnamespaced names and are registered automatically at startup.

Built-in types are organized into two groups:

- **Physical types** represent tangible assets (files, directories, repos)
  with direct read/write access and sandbox strategies.
- **Virtual types** represent abstract identities that link equivalent
  physical resources across layers and repositories. Virtual types have
  no handler, no sandbox strategy, and are never user-addable. They are
  created automatically by the system when equivalent physical resources
  are detected.

See `docs/specification.md` section "Physical vs Virtual Resources"
(~line 24548) for the full design rationale.

## fs-mount

A physical mount point on the local system. Use this type to represent
the root of a filesystem hierarchy that CleverAgents should manage.

| Field | Value |
|---|---|
| **resource_kind** | physical |
| **sandbox_strategy** | copy_on_write |
| **user_addable** | true |
| **handler** | `cleveragents.resource.handlers.fs_mount` |

### CLI Arguments

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | path | yes | Path to the mount point |

### Parent / Child Types

- **Parent types**: none (always top-level)
- **Child types**: `fs-directory`

### Auto-Discovery Rules

| Rule Type | Pattern | Description |
|---|---|---|
| `fs-directory` | `/` | Discovers the root directory under the mount |

### Capabilities

| Capability | Enabled |
|---|---|
| read | yes |
| write | yes |
| sandbox | yes |
| checkpoint | no |

---

## fs-directory

A filesystem directory. Can appear under a `git-checkout`, another
`fs-directory`, or an `fs-mount`.

| Field | Value |
|---|---|
| **resource_kind** | physical |
| **sandbox_strategy** | copy_on_write |
| **user_addable** | true |
| **handler** | `cleveragents.resource.handlers.fs_directory` |

### CLI Arguments

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | path | yes | Path to the directory |

### Parent / Child Types

- **Parent types**: `git-checkout`, `fs-directory`, `fs-mount`
- **Child types**: `fs-directory`, `fs-file`, `fs-symlink`, `fs-hardlink`

### Auto-Discovery Rules

| Rule Type | Pattern | Description |
|---|---|---|
| `fs-directory` | `*/` | Discovers immediate subdirectories |
| `fs-file` | `*` | Discovers immediate files |

### Capabilities

| Capability | Enabled |
|---|---|
| read | yes |
| write | yes |
| sandbox | yes |
| checkpoint | no |

---

## fs-file

A regular file on the local filesystem. This type is auto-discovered
only; users cannot add it manually.

| Field | Value |
|---|---|
| **resource_kind** | physical |
| **sandbox_strategy** | copy_on_write |
| **user_addable** | false |
| **handler** | `cleveragents.resource.handlers.fs_file` |

### CLI Arguments

None (auto-discovered only).

### Parent / Child Types

- **Parent types**: `fs-directory`
- **Child types**: none

### Capabilities

| Capability | Enabled |
|---|---|
| read | yes |
| write | yes |
| sandbox | no |
| checkpoint | no |

---

## git-checkout

A local git repository checkout. Serves as a top-level entry point
for version-controlled projects.

| Field | Value |
|---|---|
| **resource_kind** | physical |
| **sandbox_strategy** | git_worktree |
| **user_addable** | true |
| **handler** | `cleveragents.resource.handlers.git_checkout` |

### CLI Arguments

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | path | yes | Path to the local git repository |
| `branch` | string | no | Branch to checkout (default: current) |

### Parent / Child Types

- **Parent types**: none (always top-level)
- **Child types**: `git`, `fs-directory`

### Auto-Discovery Rules

| Rule Type | Pattern | Description |
|---|---|---|
| `git` | `.git` | Discovers git metadata |
| `fs-directory` | `**/` | Discovers all subdirectories recursively |

### Capabilities

| Capability | Enabled |
|---|---|
| read | yes |
| write | yes |
| sandbox | yes |
| checkpoint | yes |

---

## Virtual Core Resource Types

Virtual types use simple unnamespaced names that mirror their physical
counterparts. A virtual resource answers the question: "where else does
this same thing exist?" Two physical resources share a virtual parent
when they are equivalent by the virtual type's criteria.

All virtual types share these properties:

| Field | Value |
|---|---|
| **resource_kind** | virtual |
| **sandbox_strategy** | none |
| **user_addable** | false |
| **handler** | none |

All capabilities are disabled (`read: false`, `write: false`,
`sandbox: false`, `checkpoint: false`) because virtual types represent
abstract identities, not concrete locations. Tools always operate on
their physical children.

---

### file

Cross-layer file identity. Links physical `fs-file` and `git-tree-entry`
resources that represent the same file -- identical content bytes,
filename, and permissions.

- **Child types**: `fs-file`, `git-tree-entry`
- **Parent types**: none (top-level virtual)

#### Equivalence

| Criterion | Description |
|---|---|
| `content_hash` | SHA-256 of file content bytes |
| `filename` | File name component |
| `permissions` | File permission mode |

---

### directory

Cross-layer directory identity. Links physical `fs-directory` and
`git-tree` resources whose recursive contents are equivalent.

- **Child types**: `fs-directory`, `git-tree`
- **Parent types**: none (top-level virtual)

#### Equivalence

| Criterion | Description |
|---|---|
| `merkle_hash` | Merkle hash of recursive child content hashes |
| `name` | Directory name |
| `permissions` | Directory permission mode |

---

### commit

Cross-repo commit identity. Links `git-commit` resources across
different repos that share the same commit hash (e.g., fork and
upstream).

- **Child types**: `git-commit`
- **Parent types**: none (top-level virtual)

#### Equivalence

| Criterion | Description |
|---|---|
| `commit_hash` | Git commit SHA |

---

### branch

Cross-repo branch identity. Links `git-branch` resources across
different repos with the same branch name and HEAD commit hash.

- **Child types**: `git-branch`
- **Parent types**: none (top-level virtual)

#### Equivalence

| Criterion | Description |
|---|---|
| `name` | Branch name |
| `head_commit_hash` | HEAD commit SHA |

---

### tag

Cross-repo tag identity. Links `git-tag` resources across different
repos with the same tag name and target object.

- **Child types**: `git-tag`
- **Parent types**: none (top-level virtual)

#### Equivalence

| Criterion | Description |
|---|---|
| `name` | Tag name |
| `target_sha` | Target object SHA |

---

### tree

Cross-repo/cross-commit tree identity. Links `git-tree` resources
across different commits or repos that have the same tree hash.

- **Child types**: `git-tree`
- **Parent types**: none (top-level virtual)

#### Equivalence

| Criterion | Description |
|---|---|
| `tree_hash` | Git tree object SHA |
## Deferred Virtual Resource Types

Virtual resource types represent abstract identities that link equivalent
physical resources across repositories and layers. Virtual types are never
user-addable, have no sandbox strategy, and are created automatically by
the system when equivalent physical resources are detected.

Based on `docs/specification.md` ~line 23705.

---

### remote

Cross-repo remote identity. Links `git-remote` resources across different
repos that point to the same URL.

| Field | Value |
|---|---|
| **resource_kind** | virtual |
| **sandbox_strategy** | none |
| **user_addable** | false |
| **handler** | none |

#### CLI Arguments

None (system-managed only).

#### Parent / Child Types

- **Parent types**: none
- **Child types**: `git-remote`

#### Equivalence Metadata

| Field | Value |
|---|---|
| **criteria** | `url` |
| **description** | Two git-remote resources share a remote parent when they point to the same normalized URL. |

#### Capabilities

| Capability | Enabled |
|---|---|
| read | no |
| write | no |
| sandbox | no |
| checkpoint | no |

---

### submodule

Cross-repo submodule identity. Links `git-submodule` resources across
different repos with the same submodule URL and path.

| Field | Value |
|---|---|
| **resource_kind** | virtual |
| **sandbox_strategy** | none |
| **user_addable** | false |
| **handler** | none |

#### CLI Arguments

None (system-managed only).

#### Parent / Child Types

- **Parent types**: none
- **Child types**: `git-submodule`

#### Equivalence Metadata

| Field | Value |
|---|---|
| **criteria** | `url`, `path` |
| **description** | Two git-submodule resources share a submodule parent when they have the same submodule URL and path. |

#### Capabilities

| Capability | Enabled |
|---|---|
| read | no |
| write | no |
| sandbox | no |
| checkpoint | no |

---

### symlink

Cross-layer symlink identity. Links `fs-symlink` and `git-tree-entry`
(mode 120000) resources with the same name and target.

| Field | Value |
|---|---|
| **resource_kind** | virtual |
| **sandbox_strategy** | none |
| **user_addable** | false |
| **handler** | none |

#### CLI Arguments

None (system-managed only).

#### Parent / Child Types

- **Parent types**: none
- **Child types**: `fs-symlink`, `git-tree-entry`

#### Equivalence Metadata

| Field | Value |
|---|---|
| **criteria** | `name`, `target_path` |
| **description** | Two physical symlink resources share a symlink parent when they have the same name and target path. |

#### Capabilities

| Capability | Enabled |
|---|---|
| read | no |
| write | no |
| sandbox | no |
| checkpoint | no |

---

# Deferred Physical Resource Types (#330)

## git

A git repository — the object database, refs, and full history.
Parent: `git-checkout`. Children: `git-remote`, `git-branch`, `git-tag`,
`git-commit`, `git-stash`, `git-submodule`.

## git-remote

A remote URL configured on a git repo. Parent: `git`. Leaf type.

## git-branch

A named branch ref. Parent: `git`. Child: `git-commit`.

## git-tag

A tag ref (lightweight or annotated). Parent: `git`. Child: `git-commit`.

## git-commit

A specific commit object. Parents: `git-branch`, `git-tag`, `git`.
Child: `git-tree`.

## git-tree

A tree object (directory listing at a commit). Parents: `git-commit`,
`git-tree`. Children: `git-tree-entry`, `git-tree`.

## git-tree-entry

A blob entry in a tree. Parent: `git-tree`. Leaf type.

## git-stash

A stash entry. Parent: `git`. Leaf type.

## git-submodule

A submodule reference. Parent: `git`. Leaf type.

## fs-symlink

A symbolic link. Parent: `fs-directory`. Leaf type.
Sandbox: `copy_on_write`.

## fs-hardlink

A hard link (link count > 1). Parent: `fs-directory`. Leaf type.
Sandbox: `copy_on_write`.

---

# Container Infrastructure Resource Types (#831)

## container-runtime

A container runtime engine (Docker, Podman, containerd, etc.).
Top-level type with no parents. Children: `container-image`,
`container-instance`, `container-volume`, `container-network`.
Auto-discovers from Docker API endpoints and docker-compose files.
User-addable. Sandbox: `none`.

## container-image

A container image identified by tag and/or digest.
Parent: `container-runtime`. Child: `container-instance`.
Auto-discovers from Dockerfiles and docker-compose files.
User-addable. Sandbox: `none`.

## container-mount

A bind mount or volume mount inside a container instance.
Parent: `container-instance`. Children: `fs-directory`, `fs-file`.
Not user-addable (auto-discovered). Sandbox: `snapshot`.

## container-exec-env

Execution environment variables and configuration inside a container.
Parent: `container-instance`. Leaf type.
Not user-addable. Sandbox: `snapshot`.

## container-port

A port mapping between host and container (e.g. 8080:80/tcp).
Parent: `container-instance`. Leaf type.
Not user-addable. Sandbox: `snapshot`.

## container-volume

A named container volume managed by the runtime engine.
Parent: `container-runtime`. Child: `fs-directory`.
User-addable. Sandbox: `snapshot`.

## container-network

A container network (bridge, host, overlay, macvlan, or none).
Parent: `container-runtime`. Leaf type.
Not user-addable. Sandbox: `none`.
