Add agent project constellation guides and link policy

dotfiles/agents/AGENTS.md

@@ -51,3 +51,26 @@
 - The pass password store lives at `~/.password-store/`.
 - Use `pass show <entry>` to retrieve a secret, or `pass find <search-term>` to locate entries.
 - Never hardcode credentials or store them in plain text files.
+
+## Project links (local symlink index)
+- Paths in this section are relative to this file's directory (`dotfiles/agents/`).
+- Keep a local symlink index under `./project-links/` for projects that are frequently referenced.
+- Treat these links as machine-local discovery state maintained by agents (do not commit machine-specific targets).
+- Reuse existing symlinks first. If a link is missing or stale, search for the repo, then update the link with:
+
+  ln -sfn "<absolute-path-to-repo>" "./project-links/<link-name>"
+
+- If a project cannot be found quickly, do a targeted search (starting from likely roots) and only then widen the search.
+
+## Project constellation guides
+- Keep per-constellation context in `./project-guides/` and keep this file minimal.
+- When a request involves one of these projects:
+  - Open the guide first.
+  - If a mentioned repo/package name matches a guide's related-project list, open that guide even if the user did not name the constellation explicitly.
+  - Ensure required links exist under `./project-links/`.
+  - If links are missing, run a targeted search from likely roots, then create/update the symlink.
+- Guide index:
+  - `./project-guides/mova-org-agenda-api.md`
+  - `./project-guides/taffybar.md`
+  - `./project-guides/railbird.md`
+  - `./project-guides/org-emacs-packages.md`

dotfiles/agents/project-guides/mova-org-agenda-api.md

@@ -0,0 +1,29 @@
+# Mova / org-agenda-api constellation
+
+## Scope
+- Use this guide for requests involving the mova constellation, including `org-agenda-api`.
+- Primary anchor is the mova root repo; start there and branch out.
+
+## Related packages/projects (trigger list)
+- If any of these names are mentioned, open this guide for context.
+- `mova-dev`: coordination repo for the mova ecosystem and cross-repo workflows.
+- `mova`: React Native app (iOS/Android/Web).
+- `org-agenda-api`: Emacs Lisp HTTP API and deployment container.
+- `org-window-habit`: habit-tracking logic used by org workflows.
+- `org-wild-notifier`: org notification logic and scheduling behavior.
+- `dotfiles` (within mova-dev context): infra/config and deployment glue for org-agenda-api.
+
+## Symlink targets
+- `./project-links/mova-dev` -> mova constellation root.
+
+## Discovery hints
+- Check likely roots first, especially `~/Projects`.
+- Common local path is `~/Projects/mova-dev`, but do not assume it exists.
+- If the symlink is missing or stale, search by directory name first, then by repo names.
+
+## Read-first docs
+- `./project-links/mova-dev/README.md`
+- `./project-links/mova-dev/org-agenda-api/README.md` (if present)
+
+## Notes
+- Prefer treating mova root docs as canonical project context.

dotfiles/agents/project-guides/org-emacs-packages.md

@@ -0,0 +1,25 @@
+# Org / Emacs package constellation
+
+## Scope
+- Use this guide for org-related package repos, including `org-window-habit`.
+- This is especially relevant when repos are managed through local Emacs package trees.
+
+## Related packages/projects (trigger list)
+- If any of these names are mentioned, open this guide for context.
+- `org-window-habit`: org habit-tracking package/repo.
+- `org-wild-notifier`: org notification package/repo.
+- `org-agenda-api`: Emacs Lisp HTTP API project that loads org package deps.
+- `elpaca`: Emacs package manager tree where local checkouts may live.
+- `elpa`: traditional Emacs package install tree (fallback search area).
+
+## Symlink targets
+- `./project-links/org-window-habit` -> org-window-habit repo/root.
+
+## Discovery hints
+- Start with Emacs roots, especially `~/.emacs.d`.
+- Prefer checking package manager trees (including `elpaca`) before broader searches.
+- Common pattern is nested repos under `~/.emacs.d` package directories.
+
+## Read-first docs
+- `./project-links/org-window-habit/README.md`
+- `./project-links/org-window-habit/README.org` (if present)

dotfiles/agents/project-guides/railbird.md

@@ -0,0 +1,28 @@
+# Railbird constellation
+
+## Scope
+- Use this guide for requests involving railbird backend/main repo and railbird mobile app work.
+
+## Related packages/projects (trigger list)
+- If any of these names are mentioned, open this guide for context.
+- `railbird`: primary backend/main railbird repository.
+- `railbird-mobile`: primary mobile app repository.
+- `railbird2`: alternate/new-generation backend repo.
+- `railbird-mobile2`: alternate/new-generation mobile repo.
+- `railbird-docs`: documentation repository.
+- `railbird-landing-page`: marketing/landing site repository.
+- `railbird-alert-tuning`: alert/tuning and operational experimentation repo.
+- `railbird-agents-architecture`: architecture notes/prototypes for agent workflows.
+
+## Symlink targets
+- `./project-links/railbird` -> primary railbird repo.
+- `./project-links/railbird-mobile` -> railbird mobile app repo.
+
+## Discovery hints
+- Start from `~/Projects`.
+- Common backend location is `~/Projects/railbird`.
+- Mobile repo often also lives under `~/Projects`, but name/path may vary by machine.
+
+## Read-first docs
+- `./project-links/railbird/README.md`
+- `./project-links/railbird-mobile/README.md` (if present)

dotfiles/agents/project-guides/taffybar.md

@@ -0,0 +1,30 @@
+# Taffybar constellation
+
+## Scope
+- Use this guide for requests involving taffybar itself or local taffybar configuration.
+
+## Related packages/projects (trigger list)
+- If any of these names are mentioned, open this guide for context.
+- `taffybar`: top-level desktop bar library/app.
+- `imalison-taffybar`: personal taffybar configuration package/repo.
+- `gtk-sni-tray`: StatusNotifier tray integration for taffybar.
+- `gtk-strut`: X11/WM strut handling used by taffybar ecosystem.
+- `status-notifier-item`: StatusNotifier protocol/types library.
+- `dbus-menu`: DBus menu protocol support used by tray integrations.
+- `dbus-hslogger`: DBus logging helper used in ecosystem packages.
+
+## Symlink targets
+- `./project-links/taffybar-main` -> main taffybar repo.
+- `./project-links/taffybar-config` -> local taffybar config root.
+
+## Discovery hints
+- Start with `~/.config/taffybar`.
+- Common layout is:
+  - config root at `~/.config/taffybar`
+  - main repo at `~/.config/taffybar/taffybar`
+- Other taffybar-related repos may exist elsewhere; find them from docs in the main repo.
+
+## Read-first docs
+- `./project-links/taffybar-main/README.md`
+- `./project-links/taffybar-config/README.md` (if present)
+- `./project-links/taffybar-config/AGENTS.md` (if present)

dotfiles/agents/project-links/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore