# AGENTS.md — Build guide for Yado

## Project scope
Access an existing coding-agent terminal on a private host from a phone, keep the tmux session through disconnects and inspect completion notifications.

Catalogue verdict: kinda. Claude Code was never built to leave the laptop. A chat interface is easy. A terminal into a remote container, also fine. The pain starts when you want Claude, the container, and the app to forget they're three completely distinct entities and behave as one thing: signing in with one tap, when on paper that can only happen in a terminal. A chat, when underneath it is always a terminal. Infra that's fast and that keeps one person's AI away from everyone else's code. I thought that was weeks of work. It was months.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Runtime and tools: An existing Ubuntu host, tmux, ttyd, Claude Code and a private authenticated HTTPS access path.
- Before starting: An always-on user-owned host, existing SSH access and a manually authenticated agent installation; no application database or new account system.

## Stack and architecture
- An existing Ubuntu host, tmux, ttyd, Claude Code and a private authenticated HTTPS access path
- Data design: Store only access configuration and terminal/session logs where intentionally enabled; tmux owns session continuity and reconnect attaches to an explicitly selected session.
- Setup: An always-on user-owned host, existing SSH access and a manually authenticated agent installation; no application database or new account system

## Security and data integrity
- Treat the terminal as full host access. Authenticate every connection, bind services to the intended interface, and never expose unauthenticated terminal ports.
- A browser terminal grants powerful host access. Prefer private networking, protect HTTPS/auth on every route and keep agent credentials on the host; model traffic may still leave that host.
- Keep secrets outside client bundles and exported projects; document what leaves the device and make retention/deletion controls visible.

## Agent implementation rules
- Project rule — domain: Store only access configuration and terminal/session logs where intentionally enabled; tmux owns session continuity and reconnect attaches to an explicitly selected session.
- Project rule — scope and recovery: A browser terminal grants powerful host access. Prefer private networking, protect HTTPS/auth on every route and keep agent credentials on the host; model traffic may still leave that host.
- Project rule — acceptance: Lock the phone during a long command, reconnect and attempt access without credentials; the same session resumes for the owner and unauthenticated access is denied.
- Project rule — delivery: document real setup commands and permissions; do not claim a build, accuracy level, performance result or security certification that has not been demonstrated.

## Optional agent skills and references
- Recommended skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — review configuration and API defaults against the app-specific invariants and recovery boundaries above; this is not a security certification. Follow the maintainer's installation instructions and match its requirements to the chosen runtime.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this working slice using synthetic or explicitly authorized non-sensitive examples: Access an existing coding-agent terminal on a private host from a phone, keep the tmux session through disconnects and inspect completion notifications.
- Share a synthetic example export and the acceptance walkthrough; keep real customer, health, financial and source data private: Lock the phone during a long command, reconnect and attempt access without credentials; the same session resumes for the owner and unauthenticated access is denied.
- State the limits before asking someone to replace their existing tool: A browser terminal grants powerful host access. Prefer private networking, protect HTTPS/auth on every route and keep agent credentials on the host; model traffic may still leave that host.

## Engineering roadmap
1. Phase 1 — Pin the working slice and create its example input: Access an existing coding-agent terminal on a private host from a phone, keep the tmux session through disconnects and inspect completion notifications. Confirm setup: An always-on user-owned host, existing SSH access and a manually authenticated agent installation; no application database or new account system.
2. Phase 2 — Document authoritative storage and configure these safeguards in the existing tools: Store only access configuration and terminal/session logs where intentionally enabled; tmux owns session continuity and reconnect attaches to an explicitly selected session.
3. Phase 3 — Configure the existing tools and document status/troubleshooting without building another app. Treat the terminal as full host access. Authenticate every connection, bind services to the intended interface, and never expose unauthenticated terminal ports.
4. Phase 4 — Expose the app-specific limits and recovery path in context: A browser terminal grants powerful host access. Prefer private networking, protect HTTPS/auth on every route and keep agent credentials on the host; model traffic may still leave that host.
5. Phase 5 — Walk through this concrete acceptance case and preserve its exported evidence: Lock the phone during a long command, reconnect and attempt access without credentials; the same session resumes for the owner and unauthenticated access is denied. Finish the README and backup/restore instructions; report unfinished capabilities explicitly.

## Paid-product capabilities outside this build
- a real chat with your Claude account instead of a terminal driven by a phone keyboard
- a machine that sleeps at zero and wakes before you type instead of a box you pay for all week
- one tap sign in · the DIY version needs a laptop and an SSH session to log Claude in once
- diffs you can read on a small screen · screenshots you can paste in · a live preview of the app you are building
- isolation · one box means everything on it can reach everything else on it

## Implementation prompt
Build the following focused alternative to Yado. This is a deliberately limited personal or small-team substitute, not parity with the paid service.

WORKING SLICE
Access an existing coding-agent terminal on a private host from a phone, keep the tmux session through disconnects and inspect completion notifications.

SETUP AND ARCHITECTURE
Use An existing Ubuntu host, tmux, ttyd, Claude Code and a private authenticated HTTPS access path. Prerequisites: An always-on user-owned host, existing SSH access and a manually authenticated agent installation; no application database or new account system. Before integrating anything, record actual versions and permissions, plus model files or provider limits only where used, in the README; make unavailable dependencies visible rather than simulating success.

DOMAIN MODEL AND INVARIANTS
Store only access configuration and terminal/session logs where intentionally enabled; tmux owns session continuity and reconnect attaches to an explicitly selected session.

IMPLEMENTATION CONTRACT
Treat the terminal as full host access. Authenticate every connection, bind services to the intended interface, and never expose unauthenticated terminal ports. Provide an operator checklist, the exact configuration files and a status/troubleshooting procedure in the existing tools; do not create a new application UI. Preserve the last saved state if a job or save fails. Include empty, loading, permission-denied, partial and retryable-error states. Log identifiers and error categories without secret values or unnecessary private content.

APP-SPECIFIC BOUNDARY AND RECOVERY
A browser terminal grants powerful host access. Prefer private networking, protect HTTPS/auth on every route and keep agent credentials on the host; model traffic may still leave that host.

ACCEPTANCE SCENARIO
Lock the phone during a long command, reconnect and attempt access without credentials; the same session resumes for the owner and unauthenticated access is denied. Also resume the configured workflow after an interrupted operation, confirm the saved record/export remains inspectable, and document the recovery action. These are implementation acceptance requirements, not a claim that this guide has been tested.

DELIVERY
Deliver a setup/runbook folder with configuration examples, permission instructions, troubleshooting steps, an independent backup/restore procedure and the exact acceptance walkthrough. Keep using the existing applications and their data formats; do not scaffold an unrelated app or database. Implement the working slice before optional integrations; list any deferred paid-product capabilities honestly. Do not add capabilities outside the working slice just to resemble the original product.

PROJECT RULES FOR AGENTS.md
Keep the domain invariants above executable at the write boundary. Propose scope changes before adding providers or permissions. Never fabricate source evidence, publish results, identity matches or successful delivery. Preserve user originals and require an explicit confirmation for destructive changes or external publication.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.