# Using tiles directly from your repo

Instead of publishing tiles to the Tessl Registry, you can also check them directly into your repository. This is a simpler way to distribute tiles together with your code.

## When to check tiles into your repo vs using the registry

**Check tiles into your repo when:**

* You want a simple distribution method - tiles travel automatically with your code
* Context is tightly coupled to this specific codebase
* You don't need version management across multiple projects

**Use the Tessl Registry when:**

* You need centralized management and updates
* You want evaluation and review workflows
* You need automated distribution across multiple repositories
* You want to keep tiles up to date independently from code changes

## How it works

Repository-specific tiles are committed to your codebase and referenced in `tessl.json` with a `file:` source. Team members automatically get the tile when they clone the repo and run `tessl install`.

## Setup

### 1. Create the tile in your repository

```bash
cd my-repo
tessl tile new --name myworkspace/my-tile --path ./tiles/my-tile
```

This creates the tile structure:

```
my-repo/
├── tiles/my-tile/
│   ├── tile.json
│   ├── docs/                  # This repo's architecture
│   │   └── index.md
│   └── rules/                 # This repo's conventions
│       └── standards.md
└── tessl.json
```

### 2. Install it locally

Add the tile to your project by referencing it in `tessl.json` with a `file:` source:

```bash
tessl install file:./tiles/my-tile
```

This updates your `tessl.json`:

```json
{
  "name": "my-project",
  "dependencies": {
    "myworkspace/my-tile": {
      "version": "1.0.0",
      "source": "file:./tiles/my-tile"
    }
  }
}
```

### 3. Commit both to version control

```bash
git add tiles/my-tile/ tessl.json
git commit -m "Add repository-specific context tile"
```

## Team workflow

When team members clone the repository:

```bash
git clone <repo>
cd <repo>
tessl install
```

The tile installs automatically from the `file:` source in `tessl.json`. Everyone gets the same codebase-specific context.

## Updating the tile

Changes to the tile go through your normal code review process:

1. Edit tile content (docs, rules, skills)
2. Commit changes: `git commit -m "Update architecture docs"`
3. Create pull request
4. Team reviews context changes like code changes
5. Merge to main

Team members get updates when they pull and run `tessl install`.

## Benefits

* **Versioned with code** - Tile evolves alongside the codebase
* **Automatic distribution** - Team gets context when they clone
* **Code review** - Changes to patterns/architecture reviewed via PR
* **Private** - Context stays internal, no publishing needed
* **Self-documenting** - Codebase carries its own context

## Example: Monorepo workspaces

In monorepos, create workspace-specific tiles:

```
my-monorepo/
├── frontend/
│   ├── tiles/my-tile/           # Frontend patterns
│   │   ├── tile.json
│   │   ├── docs/              # React patterns
│   │   └── rules/             # UI standards
│   └── tessl.json             # References frontend tile
├── backend/
│   ├── tiles/my-tile/           # Backend patterns
│   │   ├── tile.json
│   │   ├── docs/              # API patterns
│   │   └── rules/             # Backend standards
│   └── tessl.json             # References backend tile
└── shared/
    └── tiles/my-tile/           # Cross-cutting concerns
        └── docs/              # Service communication
```

Each workspace's `tessl.json` references its local tile and any shared tiles:

```json
{
  "dependencies": {
    "myworkspace/frontend-context": {
      "source": "file:./tiles/my-tile"
    },
    "myworkspace/shared-context": {
      "source": "file:../shared/tiles/my-tile"
    }
  }
}
```

## Related

* [Developing tiles locally](https://docs.tessl.io/create/developing-tiles-locally) - Create and test tiles with local development workflow before checking them into your repo
* [Configuration files](https://docs.tessl.io/reference/configuration#tile-configuration) - Complete tile.json reference