From 7c998234efe24df59bdb1ae4b888c11c790be8bf Mon Sep 17 00:00:00 2001
From: Romain Gautier <mail@romain.sh>
Date: Tue, 7 Jul 2026 17:59:41 +0200
Subject: [PATCH] improve setup

---
 AGENTS.md  | 20 ++++++++++++++++++--
 CONTEXT.md | 33 +++++++++++++++++++++++++++++++++
 RTK.md     | 21 +++++++++++++++++++--
 3 files changed, 70 insertions(+), 4 deletions(-)
 create mode 100644 CONTEXT.md

diff --git a/AGENTS.md b/AGENTS.md
index 3d881bc..863c8d9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,8 +8,24 @@
 - url: rssbase.io
 
 ## Dev environment tips
-If `DEVENV_ROOT` env variable is defined, just run project binaries (they are available).
-If not, run them by prefixing with `devenv shell ...`
+Project binaries such as `rtk`, `tang`, `dagger`, `docker-buildx`, and `docker-compose` are provided by devenv.
+
+If `DEVENV_ROOT` env variable is defined, the devenv environment is active: run project binaries directly.
+If not, run project binaries by prefixing them with `devenv shell ...`.
+
+Examples:
+
+```bash
+# Active devenv
+rtk git status
+tang issue list
+dagger check
+
+# Outside devenv
+devenv shell rtk git status
+devenv shell tang issue list
+devenv shell dagger check
+```
 
 ## Agent skills
 
diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 0000000..d34126e
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,33 @@
+# RSSBase
+
+RSSBase is a feed reader that stores reader-owned data through AT Protocol.
+
+## Language
+
+**RSSBase**:
+The product and service at rssbase.io: a reader for subscribing to, organizing, and reading feeds.
+_Avoid_: rssbase, RSS Base
+
+**Feed reader**:
+An application that lets a reader follow feeds and read their entries in one place.
+_Avoid_: RSS reader, news reader
+
+**Reader**:
+A person using RSSBase to subscribe to feeds and read entries.
+_Avoid_: user, customer, account
+
+**Feed**:
+A syndicated source of entries that RSSBase can subscribe to and display.
+_Avoid_: RSS feed, source, channel
+
+**Entry**:
+A single item published by a feed and shown to a reader.
+_Avoid_: post, article, item
+
+**Reader data**:
+Data that belongs to a reader, such as subscriptions, preferences, and reading state.
+_Avoid_: user data, account data
+
+**AT Protocol**:
+The decentralized protocol RSSBase uses as the home for reader-owned data.
+_Avoid_: atproto, ATProto, Bluesky
diff --git a/RTK.md b/RTK.md
index 7ae285e..2ae3e55 100644
--- a/RTK.md
+++ b/RTK.md
@@ -4,9 +4,9 @@
 
 ## Rule
 
-Always prefix shell commands with `rtk`.
+Always run shell commands through `rtk`, but remember that `rtk` is a project binary provided by devenv.
 
-Examples:
+If `DEVENV_ROOT` is defined, the devenv environment is active and `rtk` is available directly:
 
 ```bash
 rtk git status
@@ -15,6 +15,17 @@ rtk npm run build
 rtk pytest -q
 ```
 
+If `DEVENV_ROOT` is not defined, wrap commands with `devenv shell` so `rtk` is available:
+
+```bash
+devenv shell rtk git status
+devenv shell rtk cargo test
+devenv shell rtk npm run build
+devenv shell rtk pytest -q
+```
+
+The same devenv rule applies to other repo-provided binaries such as `tang`, `dagger`, `docker-buildx`, and `docker-compose`.
+
 ## Meta Commands
 
 ```bash
@@ -26,7 +37,13 @@ rtk proxy <cmd>     # Run raw command without filtering
 ## Verification
 
 ```bash
+# Active devenv
 rtk --version
 rtk gain
 which rtk
+
+# Outside devenv
+devenv shell rtk --version
+devenv shell rtk gain
+devenv shell which rtk
 ```
-- 
2.51.2