Skip to content

docs(living-docs): regenerate sidecar templates #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
silversurfer562 merged 1 commit into from
May 14, 2026
Merged

docs(living-docs): regenerate sidecar templates #34

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 25 additions & 26 deletions .help/templates/sidecar/concept.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,42 @@
---
type: concept
name: sidecar-concept
feature: sidecar
depth: concept
generated_at: 2026-05-08T06:44:22.877630+00:00
source_hash: e3ed1fa3b4aba4c7d35bf2c87e344546d5ffef087a34188fb094d356b89502f8
generated_at: 2026-05-14T13:07:35.984805+00:00
source_hash: 43602ea53f0e5b79ddaad20853717644b6860bd3776d913da73a0ed8a8701c13
status: generated
---

# Sidecar

The sidecar is a local FastAPI web server that provides a browser-based interface for attune's RAG, authoring, and help systems.
## How it works

## What it does
Sidecar.

The sidecar acts as a friendly gateway between your web browser and attune's core functionality. Instead of running command-line tools directly, you interact with a local web interface that handles complex operations like corpus management, template editing, and help generation.
The main building blocks are:

The sidecar serves three main roles:
- **`CommandSpec`** — core component
- **`Config`** — Resolved config snapshot. Values are post-precedence.
- **`CorpusEntry`** — core component
- **`Registry`** — In-memory snapshot of ``~/.attune/corpora.json``.
- **`EditorSession`** — In-process state for a single ``(corpus, path)`` editing tab.

1. **Command execution** — It maintains a registry of available commands (like corpus indexing or template generation) and runs them through a unified interface
2. **File editing** — It provides real-time editing sessions for templates and other project files, with automatic conflict detection when files change on disk
3. **Configuration management** — It resolves configuration values from environment variables, config files, and defaults, presenting a consistent view across all attune tools
Under the hood, this feature spans 105 source
files covering:

## Core components
- Friendly guard for the unpublished ``attune_rag.editor`` submodule.
- Filesystem helpers shared across routes.
- FastAPI app factory — wires routes, CORS, and the origin guard.

**CommandSpec** defines what operations the GUI can perform. Each command has a name, description, argument schema, and executor function. Commands are grouped by profile (developer, author, support) to show relevant operations to each user type.
## What connects to it

**Config** provides a resolved snapshot of all configuration values. It handles the precedence chain of environment variables, config files, and built-in defaults, so other components always see consistent settings.

**EditorSession** manages the state for editing a single file through the web interface. It tracks the original content, your draft changes, and watches for external modifications to prevent conflicts.
Other parts of the codebase interact with
sidecar through these interfaces:

**Registry** maintains an in-memory view of your corpus collection from `~/.attune/corpora.json`. It knows which corpora exist, which one is currently active, and whether each corpus should warn before editing.

## Security model

The sidecar only accepts connections from localhost addresses (127.0.0.1, ::1) to prevent remote access. It generates a random authentication token on startup and stores it in a local port file, ensuring only processes on your machine can connect.

For operations that require the unpublished `attune_rag.editor` module, the sidecar provides helpful error messages rather than cryptic import failures.

## File system integration

The sidecar uses atomic writes to prevent corruption when saving files. It calculates content hashes to detect when files have changed externally, allowing the editor to prompt for conflict resolution rather than silently overwriting changes.
| Interface | Purpose | File |
|-----------|---------|------|
| `CommandSpec` | — | `sidecar/attune_gui/commands.py` |
| `Config` | Resolved config snapshot. Values are post-precedence. | `sidecar/attune_gui/config.py` |
| `CorpusEntry` | — | `sidecar/attune_gui/editor_corpora.py` |
| `Registry` | In-memory snapshot of ``~/.attune/corpora.json``. | `sidecar/attune_gui/editor_corpora.py` |
| `EditorSession` | In-process state for a single ``(corpus, path)`` editing tab. | `sidecar/attune_gui/editor_session.py` |
Loading
Loading