# 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](/create/developing-tiles-locally.md) - Create and test tiles with local development workflow before checking them into your repo
* [Configuration files](/reference/configuration.md#tile-configuration) - Complete tile.json reference


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tessl.io/distribute/repository-tiles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.