# CLAUDE.md — Runtipi App Store

> AI-consumable project documentation for GeiserX/runtipi-appstore.

## Project Overview

Community [Runtipi](https://runtipi.io/) app store containing 17 self-hosted Docker applications by [GeiserX](https://github.com/GeiserX). Users add this store to their Runtipi instance via Settings > App Stores.

## Architecture

```
apps/
  <app-id>/
    config.json          # App metadata, form fields, categories
    docker-compose.yml   # Docker Compose with x-runtipi extensions
    metadata/
      description.md     # Long description for Runtipi UI
      logo.jpg           # 512x512 square logo
  app-info-schema.json   # JSON Schema for config.json validation
```

## Key Conventions

- Each app folder name MUST match the `id` field in its `config.json`
- Docker images are from Docker Hub (`drumsergio/*`)
- All compose files use `x-runtipi` dynamic compose format (schema_version 2)
- Web UI apps declare `x-runtipi: is_main: true` + `internal_port` on the main service
- Headless apps omit `is_main` and set `no_gui: true` in config.json
- Runtipi handles Traefik routing and networking from `x-runtipi` metadata — no manual labels
- Template variables: `${APP_DATA_DIR}`, `${APP_PORT}`, `${APP_DOMAIN}`, `${TZ}`, `${APP_PROTOCOL}`
- Form fields generate environment variables referenced in compose
- Logos are 512x512 JPEG, 1:1 aspect ratio
- All image tags are pinned to specific versions (no `:latest`)
- `min_tipi_version` is set to `4.5.0` (required for x-runtipi YAML support)

## Apps Included

| App ID | Source Repo | Web UI |
|--------|-------------|--------|
| telegram-archive | Telegram-Archive | Yes (port 8000) |
| genieacs | genieacs-container | Yes (port 3000) |
| lynxprompt | LynxPrompt | Yes (port 3000) |
| pumperly | Pumperly | Yes (port 3000) |
| cashpilot | CashPilot | Yes (port 8080) |
| paperless-telegram-bot | paperless-telegram-bot | No |
| telegram-slskd-bot | telegram-slskd-local-bot | No |
| telegram-delay-cloner | telegram-delay-channel-cloner | No |
| jellyfin-telegram-sync | jellyfin-telegram-channel-sync | No |
| jellyfin-encoder | jellyfin-encoder | No |
| audio-transcode-watcher | audio-transcode-watcher | No |
| nginx-mailer | nginx-mailer | Yes (port 80) |
| way-cms | Way-CMS | Yes (port 5000) |
| epublangmerger | ePubLangMerger | Yes (port 3838) |
| duplicacy-exporter | duplicacy-exporter | No (Prometheus metrics on 9750) |
| akou | akou | Yes (port 8476) |
| vettarr | vettarr | Yes (port 4850) |

## Adding a New App

1. Create `apps/<id>/` directory
2. Add `config.json` following `app-info-schema.json`
3. Add `docker-compose.yml` with `x-runtipi: schema_version: 2` top-level and `is_main`/`internal_port` on main service
4. Add `metadata/description.md` and `metadata/logo.jpg`
5. Ensure `id` matches folder name
6. Test with Runtipi before committing

*Generated by [LynxPrompt](https://lynxprompt.com) CLI*


<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6cd5cc61 -->
## Beads Issue Tracker

This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.

### Quick Reference

```bash
bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work
```

### Rules

- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Run `bd prime` for detailed command reference and session close protocol
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files

**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

## Agent Context Profiles

The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.

- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.

## Session Completion

This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.

1. **File issues for remaining work** - Create beads for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **Handle git/sync by active profile**:
   ```bash
   # Conservative/minimal/default: report status and proposed commands; wait for approval.
   git status

   # Team-maintainer opt-in only, unless current instructions forbid it:
   git pull --rebase
   git push
   git status
   ```
5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step

**Critical rules:**
- Explicit user or orchestrator instructions override this Beads block.
- Do not commit or push without clear authority from the active profile or the current user request.
- If a required sync or push is blocked, stop and report the exact command and error.
<!-- END BEADS INTEGRATION -->

## Where the tracker syncs

This repo is public, so its tracker syncs only to the private remote named by `sync.remote` in `.beads/config.yaml`. The block above says sync uses "your git remote". Here that never means this GitHub repo. Don't add it as a Dolt remote and don't push `refs/dolt/*` to it.