# Resources — Detailed Reference

## Resource Type Hierarchy

### Physical Types — Git Layer

| Type | User Addable | Sandbox | Description |
|------|-------------|---------|-------------|
| `git` | yes | `none` | A git repository (object DB, refs, full history). May be local or remote. |
| `git-remote` | no | (none) | A remote URL configured on a git repo. Auto-discovered child of `git`. |
| `git-branch` | no | (inherits) | A named branch ref. Auto-discovered child of `git`. |
| `git-tag` | no | (inherits) | A tag ref. Auto-discovered child of `git`. |
| `git-commit` | no | (inherits) | A specific commit object. Auto-discovered child of `git-branch`. |
| `git-tree` | no | (inherits) | A tree object (directory listing at a commit). Auto-discovered child of `git-commit`. |
| `git-tree-entry` | no | (inherits) | A blob entry in a tree (specific file at specific path). Auto-discovered child of `git-tree`. |
| `git-stash` | no | (inherits) | A stash entry. Auto-discovered child of `git`. |
| `git-submodule` | no | (inherits) | A submodule reference. Auto-discovered child of `git`. |

### Physical Types — Git Checkout

| Type | User Addable | Sandbox | Description |
|------|-------------|---------|-------------|
| `git-checkout` | **yes** | `git_worktree` | A locally checked-out git repo. **Composition type** — auto-discovers `git` child and `fs-directory` child. Most users register this type. |

### Physical Types — Filesystem Layer

| Type | User Addable | Sandbox | Description |
|------|-------------|---------|-------------|
| `fs-mount` | **yes** | `copy_on_write` | A physical mount point. Root directory auto-discovered as `fs-directory` child. |
| `fs-directory` | **yes** | `copy_on_write` | A directory. Can be standalone, root of fs-mount, worktree root of git-checkout, or subdirectory. |
| `fs-file` | no | (inherits) | A regular file. Auto-discovered child of `fs-directory`. |
| `fs-symlink` | no | (inherits) | A symbolic link. Auto-discovered child of `fs-directory`. |
| `fs-hardlink` | no | (inherits) | A hard link (link count > 1). Auto-discovered child of `fs-directory`. |

### Virtual Types (abstract identity; never user-addable; no sandbox)

| Type | Links | Answers |
|------|-------|---------|
| `file` | `fs-file` ↔ `git-tree-entry` | "This file on disk and this blob in git are the same file" |
| `directory` | `fs-directory` ↔ `git-tree` | "This directory on disk matches this tree object in git" |
| `symlink` | `fs-symlink` ↔ `git-tree-entry` (mode 120000) | "This symlink on disk and this git entry are the same symlink" |
| `commit` | `git-commit` (cross-repo) | "This commit exists in both repos" |
| `branch` | `git-branch` (cross-repo) | "These repos share a branch at the same HEAD" |
| `tag` | `git-tag` (cross-repo) | "These repos share a tag" |
| `remote` | `git-remote` (cross-repo) | "These repos share the same upstream" |
| `submodule` | `git-submodule` (cross-repo) | "These repos reference the same submodule" |
| `tree` | `git-tree` (cross-commit/cross-repo) | "These tree objects have identical content" |

---

## Sandbox Strategies

| Strategy | Resource Types | Rollback |
|----------|---------------|---------|
| `git_worktree` | `git-checkout` | `git reset --hard <commit_sha>` |
| `copy_on_write` | `fs-mount`, `fs-directory` | Restore from snapshot |
| `overlay` | Custom | Discard overlay writes since checkpoint |
| `transaction_rollback` | Database types | `ROLLBACK TO SAVEPOINT <name>` |
| `none` | `git`, APIs, cloud services | No rollback; user proceeds at own risk |

---

## Resource Type Inheritance

```yaml
# Example: devcontainer-instance inherits container-instance
name: devcontainer-instance
inherits: container-instance
description: "A container provisioned from a devcontainer.json"

cli_args:
  - name: config-path
    type: path
    required: false
    description: "Path to .devcontainer/devcontainer.json"

handler:
  class: DevcontainerHandler
  module: cleveragents.resource.handlers.devcontainer
```

**Inheritance rules:**
1. Single inheritance only (no diamond)
2. Maximum chain depth: 5 levels
3. No circular inheritance (validated at registration)
4. Built-in types may not inherit from custom (namespaced) types
5. Removing a parent type is prohibited while subtypes exist

**Field resolution:** Walk inheritance chain from most specific to root. Subtype value wins (override). If omitted, parent's value is inherited.

**Collection field merging:** `cli_args`, `child_types`, `parent_types` use additive merging by default. Use `<field>_replace: true` to replace entirely.

**Polymorphism:** Tools bound to a parent type automatically work with all subtypes.

---

## Execution Environment Routing (6-Level Precedence)

When a plan enters Execute, the runtime determines WHERE each tool runs:

| Priority | Source | Condition |
|----------|--------|-----------|
| 1 (highest) | Plan-level `execution_environment` with `priority: override` | `agents plan use --execution-environment R --execution-env-priority override` |
| 2 | Project-level `execution_environment` with `priority: override` | `agents project context set --execution-environment R --execution-env-priority override` |
| 3 | Nearest-ancestor devcontainer (auto-detected) | Lazy-built on first access |
| 4 | Plan-level `execution_environment` with `priority: fallback` | Used only when no devcontainer detected |
| 5 | Project-level `execution_environment` with `priority: fallback` | Used only when no closer-scoped environment |
| 6 (default) | Host | The local operating system |

**Tool-level environment preferences:**
- `environment.required: container` → tool MUST run in container; error if router resolves to host
- `environment.preferred: container` → hint only; runs wherever router places it
- `environment.specific: local/api-dev` → route to specific named resource regardless of chain

---

## Devcontainer Integration

Auto-discovered when a `git-checkout` or `fs-directory` resource contains a `.devcontainer/` directory.

**Lifecycle:**
1. During auto-discovery: created in `detected (not built)` state
2. First time execution environment router selects it: built and started (lazy activation)
3. Remains available for subsequent plan executions until explicitly stopped or removed

**Resource type:** `devcontainer-instance` (inherits `container-instance`)

**CLI:**
```bash
# Devcontainer discovered automatically on git-checkout registration
agents resource add git-checkout local/my-repo --path /path/to/repo

# View discovered devcontainer
agents resource tree local/my-repo

# Stop the running container
agents resource stop local/my-repo-devcontainer

# Rebuild the container (e.g. after devcontainer.json changes)
agents resource rebuild local/my-repo-devcontainer
```

---

## Working with Resources

```bash
# Register a git checkout (auto-discovers git + fs-directory children)
agents resource add git-checkout local/api-repo \
  --path /repos/api-service \
  --branch main

# Register a standalone directory
agents resource add fs-directory local/config-dir \
  --path /etc/myapp

# List all resources
agents resource list

# Filter by type
agents resource list --type git-checkout

# Explore resource structure
agents resource show local/api-repo
agents resource inspect local/api-repo
agents resource tree --depth 3 local/api-repo

# Inspect a specific file within a resource
agents resource inspect --file src/main.py local/api-repo

# Link a child resource to a parent
agents resource link-child local/api-repo local/some-subdir

# Remove a resource
agents resource remove local/api-repo

# Custom resource type
agents resource type add --config ./types/my-db-type.yaml
agents resource type list
agents resource type show local/my-db-type
```
