Your actions after the 2026-11-01 run
Everything below needs you, not the agent. It has three parts:
- Part 1: decisions. Each says what it means and what happens now, with a recommendation.
- Part 2: setup, step by step.
- Part 3: reviewing and merging.
None of this blocks the code work that’s still queued. Reply by number, for example “1 yes, 2 yes, 6: 30 days”.
Already done, nothing to do:
- The deploy token (
CLOUDFLARE_API_TOKEN) and account ID are in GitHub (P0.04). - The content buckets and the four main queues exist (P0.02).
ADMIN_BASE_URLis already set in the code for staging and production.
The order to do things in
Section titled “The order to do things in”Part 1 (decisions 1–14) is done. Your answers are in the decisions log. What’s left is setup and merging, in this order. Each step says what it unblocks.
- Start the slow requests first (5 minutes; they take days to come back):
- email Niobi for the API credentials, sandbox access, webhook IP list and top-up limits (item 21.5);
- get the Maansa API docs and an account (decision 13).
- Merge #38, then review and merge the code PRs in stack order (items 25–27).
- Safe to start now: until the databases exist (step 5), the deploy pipeline skips the deploy steps instead of failing.
- Merging early keeps the stack short and clears the secret-scan failures on #40–#48.
- Cloudflare resources (15 minutes): the two error queues (item 17) and the two Pages projects (item 18).
- Secrets (15 minutes):
CREDENTIAL_KEY_V1(item 15) andBETTER_AUTH_SECRET_ADMIN(item 16), each for staging and production. Check thatBETTER_AUTH_SECRET_APPis set too. - Server work (item 22): say “start P0.08” and I’ll prepare the recipes and exact commands. This is the big unblocker: databases, the gateway and the private connection. Nothing works live until it’s done.
- Third-party accounts (item 21): Turnstile, Resend, Google sign-in, Datadog. Do these alongside step 5. Sign-up in staging needs Turnstile and Resend.
- After the first successful staging deploy:
- attach
app.andapp-staging.(item 19); - sign up and make yourself the first Admin (item 20).
- attach
- Then: the payment relay (item 23), once step 5 is done and Niobi has replied.
- Later, when I ask: canary keys and the rate-limit token (item 24).
Anytime: docker stop ra-concurrency-pg (item 28).
Part 1. Decisions
Section titled “Part 1. Decisions”1. Which charting tool draws the graphs
Section titled “1. Which charting tool draws the graphs”The usage and billing screens show graphs, and the specs don’t name a tool for drawing them. I used Recharts, which the UI kit we already use is built on.
- If you keep it: nothing changes.
- If you change it: every chart is redrawn with another tool, about a day of work.
- Recommendation: keep Recharts.
2. The characters in an API key, and their order
Section titled “2. The characters in an API key, and their order”A customer’s key looks like sk-ra- followed by random letters and digits. To make those characters, the code uses a fixed list of 62 symbols: digits, then capitals, then lowercase (0-9A-Za-z). The order matters because the last few characters of each key are a checksum, which lets us reject a mistyped key straight away. Once real keys exist, changing the order would make every issued key fail that check.
- Recommendation: confirm
0-9A-Za-z. It is the usual order. The only deadline is before the first real key is issued.
3. Which currency a new customer gets when theirs isn’t offered
Section titled “3. Which currency a new customer gets when theirs isn’t offered”At sign-up, a workspace’s currency is picked from the customer’s country. If that country’s currency isn’t switched on yet (say a customer in Ghana before GHS is enabled), the code gives them USD. If USD is off too, they get the first currency that is on.
- The alternative: block sign-up from countries whose currency isn’t on.
- Recommendation: keep the USD fallback, so nobody is turned away.
4. What an ordinary team member may do
Section titled “4. What an ordinary team member may do”An organisation has Owners, Admins and Members. Two things weren’t specified:
- (a) May a Member see the list of people in their organisation? Now: yes, read-only.
- (b) May a Member create their own API keys in workspaces they belong to? Now: yes. They can manage only their own keys; managing other people’s keys stays with Owners and Admins.
- Recommendation: yes to both. A developer on the team needs a key to do their work.
5. The name written in the audit log when someone changes a rate limit
Section titled “5. The name written in the audit log when someone changes a rate limit”When staff change a rate limit, the audit log records an entry with a fixed name. Two documents disagree on that name: the database spec says rate_limit.changed, the task text says ratelimit.updated. The code follows the database spec. This is only a label; no customer sees it.
- Recommendation: keep
rate_limit.changed. The task text will be corrected to match.
6. How far back customers can see their request history
Section titled “6. How far back customers can see their request history”The Logs screen lists every API call a customer made. Its date picker now goes back 90 days. Nothing has been decided yet about how long we actually keep those records, and keeping them longer costs storage. Customers can’t see further back than we keep.
- Options: 30, 90 or 180 days. Stored prompts and replies may need a shorter limit than the basic records (time, model, tokens, cost).
- Recommendation: 90 days for the basic records and 30 days for stored prompts and replies. A product call, so yours.
7. How customers pay for credits, and the limits
Section titled “7. How customers pay for credits, and the limits”When a customer tops up, payment goes through Niobi. Not decided yet:
- (a) What the customer sees. One or more of:
- a Niobi-hosted payment page (we send them there and they come back);
- a mobile-money prompt (the customer types their phone number and approves on their phone, as with M-Pesa);
- card entry.
- (b) Smallest and largest top-up in each currency, for example KES 500 to KES 500,000.
The screen supports all of these and currently shows a hosted-page link. Ask Niobi what they offer in each country, then tell me.
8. Charging for usage the system couldn’t bill at the time
Section titled “8. Charging for usage the system couldn’t bill at the time”Rarely, a request is served but couldn’t be charged when it happened, for example because of a glitch. Staff see these on an admin screen and can charge or forgive each one. When staff click “charge”, the code:
- uses today’s price (not the price on the day of the request);
- refuses if the customer hasn’t got enough credits, rather than taking what’s there and leaving a debt.
- Recommendation: keep both. Partial charges create debts we don’t otherwise allow.
9. How profit is calculated on the admin margin screen
Section titled “9. How profit is calculated on the admin margin screen”We pay providers in US dollars and charge customers in their currency. To show profit, the provider cost has to be converted. The code uses the latest exchange rate, not the rate on the day of each request. Customers aren’t affected; this only changes a staff report.
- Recommendation: keep it for launch. Switch to the day’s rate later if finance wants exact historical figures.
10. A request asking for a longer answer than a model allows
Section titled “10. A request asking for a longer answer than a model allows”A developer can ask for an answer of up to N tokens (pieces of words). Each model has a ceiling.
- The decisions log says: if they ask for more than the ceiling, quietly lower it to the ceiling. The code does that.
- The API error list (
api-errors.md) still describes an error for this case that we never send. - Recommendation: remove that unused error from the list. This only tidies the document.
11. Three limits inside the API
Section titled “11. Three limits inside the API”- (a) Charged twice by accident. If a developer’s program sends the same request twice (a retry after a network blip), we must not charge twice. We treat an identical request within 30 seconds as the same one. If the developer adds their own request ID, we remember it for 24 hours.
- (b) Reserving credits before answering. Before calling the AI model we set aside enough credits for the longest possible answer, then return what wasn’t used. If a model has no stated maximum, we assume 4,096 tokens (about 3,000 words).
- (c) How much of each conversation we store. For customers who turned on storage, we keep up to 1 MB of each request and reply (roughly 500 pages of text). Past that, the stored copy is cut and marked as cut. The customer’s actual reply is never cut.
- Recommendation: keep all three. They are common industry values.
12. A database permission for the background worker
Section titled “12. A database permission for the background worker”A background process records usage and also updates each API key’s “last used” time. For safety it signs in to the database with a restricted login that can only write usage records. “Last used” lives in a different area, so that login can’t update it.
- Option A: let the restricted login update that one field.
- Option B: have the process use the dashboard’s broader login.
- Recommendation: A. It keeps the smallest set of permissions.
13. Where exchange rates come from
Section titled “13. Where exchange rates come from”Prices are set in dollars and shown in local currencies, so we need a daily exchange rate for each one. The free source we use covers USD and some major currencies, but not most African ones (KES, NGN, GHS and others).
- Now: for those currencies, staff type the rate by hand on the admin FX screen, and the daily job lists which ones are missing.
- To fix it: pick a paid source that covers them (for example Open Exchange Rates, or rates supplied by Niobi). This is already in the decisions table as open.
14. Testing against the real database type
Section titled “14. Testing against the real database type”Our automated tests run against a lightweight copy of the database. It once hid a bug that the real database would have caught; I fixed that bug. I’d like the dashboard’s tests to also run against a real database in CI. Cost: a few minutes per CI run, no money.
- Recommendation: yes.
Part 2. Setup, step by step
Section titled “Part 2. Setup, step by step”What a “secret” is: a password-like value that the app needs but that must never be in the code. You create it, save a copy in Bitwarden, and hand it to Cloudflare with one command. The app reads it when it runs. The agent never sees or sets these.
Before you start (once):
- Open Terminal and go to the code:
cd ~/Code/router-africa. - Sign in to Cloudflare:
npx wrangler login. A browser opens; approve it.
How to make a random secret: run openssl rand -base64 32. It prints a random string. Copy it.
How to hand a secret to Cloudflare:
- Go to the app’s folder.
- Run
npx wrangler secret put <NAME> --env staging. Paste the value when asked and press Enter. - Repeat with
--env production.
If the app has never been deployed, Wrangler asks whether to create it. Answer yes.
15. Key-encryption secret: CREDENTIAL_KEY_V1 (both APIs)
Section titled “15. Key-encryption secret: CREDENTIAL_KEY_V1 (both APIs)”What it’s for: each customer key has a matching hidden key at our gateway. We store that hidden key encrypted, and this secret is what locks and unlocks it. Until it is set, creating or changing keys answers “unavailable” (503) in staging and production.
Rules:
- Use one value per environment, a different one for staging and for production.
- The same value goes on both apps, because one locks and the other unlocks.
Steps:
- Run
openssl rand -base64 32and save the result in Bitwarden as “CREDENTIAL_KEY_V1 – staging”. - Run
cd apps/dashboard-api && npx wrangler secret put CREDENTIAL_KEY_V1 --env staging, paste the value, thencd ../... - Run
cd apps/api && npx wrangler secret put CREDENTIAL_KEY_V1 --env staging, paste the same value, thencd ../... - Repeat steps 1–3 for production with a new value, using
--env production.
Never lose it. Without it, every stored hidden key is unreadable. Bitwarden is the backup.
16. Staff-console sign-in secret: BETTER_AUTH_SECRET_ADMIN
Section titled “16. Staff-console sign-in secret: BETTER_AUTH_SECRET_ADMIN”What it’s for: it signs staff console logins. Customer logins use a different secret, BETTER_AUTH_SECRET_APP. Keeping them separate means a stolen customer login can never open the staff console. PR #44 needs it.
Steps:
- Run
openssl rand -base64 32and save it in Bitwarden as “BETTER_AUTH_SECRET_ADMIN – staging”. - Run
cd apps/dashboard-api && npx wrangler secret put BETTER_AUTH_SECRET_ADMIN --env staging, paste the value, thencd ../... - Repeat with a new value and
--env production.
Make sure:
BETTER_AUTH_SECRET_APPis set the same way, with its own value. If it isn’t set yet, do it now.- Changing either secret later signs everyone of that kind out, which is safe but disruptive.
17. Error-queue for failed usage records
Section titled “17. Error-queue for failed usage records”What it’s for: usage records travel through a queue to the worker that writes them. If a record is damaged and can’t be written, it goes to a side queue (a “dead-letter queue”) so we can inspect it instead of losing it. Two of these side queues are missing.
Steps:
- Run
npx wrangler queues create usage-events-dlq-staging. - Run
npx wrangler queues create usage-events-dlq-production. - Tell me they exist. I’ll switch the usage worker on in the code (it’s held back in PR #37 until then).
18. The two websites (dashboard and staff console)
Section titled “18. The two websites (dashboard and staff console)”What it’s for: the customer dashboard and the staff console are websites hosted on Cloudflare Pages. Each needs a project to deploy into.
Steps:
- Run
npx wrangler pages project create router-africa-dashboard --production-branch main. - Run
npx wrangler pages project create router-africa-admin --production-branch main.
The names must match exactly; the deploy pipeline uses them. Then do item 19.
19. Web addresses
Section titled “19. Web addresses”What happens on its own: the public API addresses (api.router.africa, api-staging.router.africa) are created automatically on the first deploy.
What you do by hand: attach the customer dashboard’s addresses.
Steps (Cloudflare dashboard):
- Go to Workers & Pages → router-africa-dashboard → Custom domains → Set up a custom domain.
- Enter
app.router.africaand confirm. Cloudflare creates the DNS record. - Do the same for
app-staging.router.africa. - Point that staging address at the staging copy of the site instead of the live one:
- Go to DNS → Records for router.africa.
- Find the
app-stagingrecord. - Edit its target to
staging.router-africa-dashboard.pages.devand save.
- Skip
admin.andadmin-staging.for now. They stay unattached until staff-only access protection (Cloudflare Access, P8.01) is in place, so the console is never public.
Do this after the first staging deploy, so the sites have content.
20. Make yourself the first staff Admin
Section titled “20. Make yourself the first staff Admin”What it’s for: staff accounts can’t be created from the app; the first Admin has to be set directly in the database.
Steps:
- Sign up on the dashboard with your work email.
- Turn on two-step sign-in in Settings. Staff accounts require it.
- Ask me (or run it yourself) to apply this database change for your email:
UPDATE users SET role = 'admin' WHERE email = '<your email>'; - Sign in at the staff console.
When: this needs the databases from item 22, so do it after that.
21. Third-party accounts (P0.05)
Section titled “21. Third-party accounts (P0.05)”What it’s for: outside services the app depends on. Do each for staging and for production. Save every value in Bitwarden.
- Turnstile (the bot check on sign-up):
- In Cloudflare, go to Turnstile → Add site.
- Add the
app.andapp-staging.addresses. - Copy the site key and the secret key.
- Send me the site keys. They’re public; they go in the code.
- Set the secret with
wrangler secret put TURNSTILE_SECRET_KEYin theapps/dashboard-apifolder, as above.
- Resend (sends sign-up and password emails):
- Make an account and add the domain
router.africa. - Resend shows three DNS records. Add them under DNS → Records in Cloudflare.
- Wait until Resend shows Verified.
- Create an API key and set it as
RESEND_API_KEYin theapps/dashboard-apifolder.
- Make an account and add the domain
- Google sign-in:
- In Google Cloud Console, go to APIs & Services → Credentials → Create OAuth client (Web application).
- Add this as an authorised redirect:
https://app.router.africa/api/auth/callback/google. - Add the same with
app-staging. - Set
GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETin theapps/dashboard-apifolder. - GitHub and GitLab sign-in work the same way. They are optional for launch.
- Datadog (monitoring):
- Create the account.
- Keep its API key in Bitwarden. It’s used later, when monitoring is wired up.
- Niobi (payments). Ask them for:
- API credentials;
- their request-signing example code;
- sandbox (test) access;
- the list of IP addresses their payment notifications come from;
- the answers to decision 7.
- the web address their hosted checkout page loads from (we must allow it in our security settings to show it inside the dashboard);
- confirmation that their checkout page may be shown inside
app.router.africa(embedded in our page).
22. Server work on the droplet (P0.08–P0.11)
Section titled “22. Server work on the droplet (P0.08–P0.11)”What it’s for:
- The gateway (Bifrost) talks to OpenAI, Anthropic and other providers. It runs on our DigitalOcean server (the “droplet”).
- The main database (Postgres) also runs there, one copy for staging and one for production.
- Cloudflare needs a private, non-public path to both.
This is the biggest remaining block. Until it’s done, the app can’t answer AI requests (“unavailable” outside tests) or store data in staging and production.
The order:
- Databases and staging gateway (P0.08):
- I write the install recipes: the database setup, with daily backups to the R2 bucket for production, and the gateway settings for staging.
- You run the install commands I give you on the server.
- You check that production’s gateway settings didn’t change.
- Deploy helper (P0.09):
- I write the recipe for a small program on the server that lets GitHub deploy server-side parts.
- You install it and register it with GitHub.
- You set the GitHub variable
SELF_HOSTED_RUNNERtotrue(GitHub → repo → Settings → Secrets and variables → Actions → Variables).
- Private connection (P0.10):
- You create a Cloudflare Tunnel in Zero Trust: Networks → Tunnels → Create. Keep the token in Bitwarden.
- I write the recipe that runs it on the server, and the filter that lets the public API reach only the “answer a prompt” part of the gateway.
- You create the four private links in Cloudflare (gateway-inference, gateway-management, niobi-proxy, postgres) and send me their IDs. I put them in the code.
- One provider key on staging (P0.11):
- You add one cheap provider key (for example an OpenAI key with a $10 limit) in the staging gateway’s dashboard.
- Then I check the whole path end to end (P0.13). The gateway connection and the remaining parts of the API go live after that.
To start: the run that’s going now excludes server work, by your instruction. Say “start P0.08” and I’ll prepare step 1 and give you the exact commands.
23. Payment relay (niobi-proxy, phase 6)
Section titled “23. Payment relay (niobi-proxy, phase 6)”What it’s for: a small service on the droplet that talks to Niobi for us, so that Niobi only ever sees one fixed address, the droplet’s. Until it exists, top-ups answer “unavailable” outside development.
Order: it needs item 22 done and the Niobi details from item 21 first. Then I build it and you install it the same way as step 1 of item 22.
24. Later, not now
Section titled “24. Later, not now”- Canary keys: after a deploy, the pipeline sends one tiny test request. It needs a test API key per environment, saved as GitHub secrets
STAGING_CANARY_API_KEYandPROD_CANARY_API_KEY. They can only be made once the test workspace exists (P1.07). I’ll tell you when. - Rate-limit token: a Cloudflare token for the staff screen that changes API rate limits. The screen isn’t connected to Cloudflare yet, so don’t create it until I ask. The real launch limits are also still to be set; today’s values are placeholders.
Part 3. Review and merge
Section titled “Part 3. Review and merge”25. Merge the code PRs, in order
Section titled “25. Merge the code PRs, in order”- What’s waiting: code PRs #19–#44, stacked, so each one is built on the one before.
- Order: the merge order is in the context README under Current status.
- Review first: you can run
/ra-dev-pr-review allto check them against the specs.
26. Merge #38 early
Section titled “26. Merge #38 early”#38 updates the automated checks, including the secret scan, which looks for passwords committed by mistake.
- What’s failing: #40–#44 fail that scan.
- Why it isn’t real: it flags two fake example values (a made-up test key and a development-only placeholder). #38 already marks both as allowed.
- What to do: merge #38 first, then I’ll rebase the later PRs onto it and the scan passes.
27. Context PRs
Section titled “27. Context PRs”- #17: today’s report and status updates.
- #18: the
/ra-dev-pr-reviewskill.
28. Tidy up
Section titled “28. Tidy up”A temporary test database is still running on your laptop. Stop it with docker stop ra-concurrency-pg.