chore: initial agent instructions

AGENTS.md

@@ -0,0 +1,39 @@
+# AGENTS.md
+
+Guidance for AI agents (and humans) working in this repository.
+
+## What this is
+
+A personal Bash toolkit dispatched through a single parent command, `ayo.sh` (aliased `yo`). Each capability is its own `*.sh` script; `ayo.sh` routes to them. One larger component, `tasks`, is a standalone Python curses TUI. There is no build step and no unit-test framework.
+
+## Running & developing
+
+- **Entry point:** `./ayo.sh <command> [args]`, normally via the `yo` alias. An unmatched command prints `Command not found`.
+- **Setup** (from the README): `cp example.conf ~/ayo.conf` and edit the values; alias `yo` → `<repo>/ayo.sh`; `pnpm install` (installs the Husky git hook).
+- **Config is required and lives outside the repo** at `~/ayo.conf` (the repo ships `example.conf` as the template). Almost every script starts with `. ${HOME}/ayo.conf` then `. ${scripts_dir}/functions.sh`, so nothing works until `~/ayo.conf` exists and defines `scripts_dir`.
+- **Tests:** there is no framework — `npm test` deliberately errors. The closest thing is the `tasks` app's self-test: `./tasks selftest` (exercises create/redate/log/move on a throwaway temp store). Syntax-check the Python with `python3 -c "import ast; ast.parse(open('tasks').read())"`.
+- **Git remotes:** `gh` (GitHub), `sh` (SourceHut), `origin` (git.ayo.run). The Husky `post-commit` hook auto-pushes to `gh` and `sh`.
+
+## Architecture
+
+**Dispatcher + sourcing.** `ayo.sh` is one large `case $1 in` mapping short aliases and full names to scripts. Two-letter shortcuts are namespaced by first letter — `j*` journal, `n*` notes, `g*` git (e.g. `ns` = notes sync, `gd` = git diff, `ja` = journal append). Sub-scripts are invoked by **sourcing** (`. ${scripts_dir}/foo.sh "$@"`), not executing — they run in `ayo.sh`'s own shell. Two consequences to respect:
+
+- An `exit` in any sub-script kills the whole `ayo.sh` invocation.
+- Env vars and shell state set in one script leak into the dispatcher and siblings.
+
+**Config-as-variables.** All paths and preferences come from `~/ayo.conf` variables (`scripts_dir`, `notes_dir`, `tasks_dir`, `tasks_template`, `editor`, ollama hosts, display outputs, …). Never hardcode a path — read the config variable. When adding a configurable location, add it to `example.conf`, and if the launcher/app needs it, pass it through `ayo.sh` as an env var — this is how `tasks_dir`/`tasks_template` become the `TASKS_HOME`/`TASKS_TEMPLATE` seen by the `tasks` app.
+
+**Shared helpers** live in `functions.sh` (sourced after config). The key one is `notesSync()`: pings the notes remote, then pull-rebase / add / commit / push of `notes_dir`, with a timeout-and-retry loop when offline. `editFile()` wraps "sync → open editor → sync". The notes store is itself a git repo that gets synced around edits.
+
+**The `tasks` app** is the most substantial subsystem — a single-file Python 3 curses TUI (no file extension, stdlib only) for managing markdown task files. Its data model is enforced in code, and these invariants matter when editing it:
+
+- **Status is the folder** a task lives in (`backlog` → `next` → `in-progress` → `done`); there is no status field.
+- **The filename's date is the last-updated date** — every mutation re-dates the filename, while the `id:` frontmatter is a stable handle that is never rewritten.
+- Moves/renames use `git mv` when the file lives in a repo.
+- New tasks render from a **single template file** — the source of truth for a task's shape — at `$TASKS_TEMPLATE` (default `$TASKS_HOME/_TEMPLATE.md`), auto-seeded if missing. Inline `#` field comments and HTML comments in the template are stripped on render.
+- It runs as a curses TUI given a TTY, and otherwise exposes headless subcommands (`list`, `show`, `new`, `move`, `selftest`). `ayo.sh` launches it wrapped in a `notes.sh sync` before and after.
+
+## Conventions
+
+- Editor artifacts (`.*.un~`, `*.swp`) litter the tree but are gitignored (`*~`, `*swp`); ignore them and don't commit them.
+- Targets Linux; the README notes macOS differences (e.g. `timeout` via `brew install coreutils`).

CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+The guidance for this repository is maintained generically in [AGENTS.md](./AGENTS.md) so it applies to any coding agent. Read it and follow it.
+
+@AGENTS.md