Procedures¶
Find instructions for a development or operations task. These guides serve both developers and coding agents; each link opens the maintained procedure in its existing documentation.
Start with the task below, then check the guide's prerequisites, working directory, and environment before running commands. Follow its verification steps to confirm the result. Agents must also read the applicable repository instructions; a guide does not expand the user's authorization.
Setup¶
| Task | Procedure |
|---|---|
| Prepare a workspace and download dependencies/environment files | Development setup |
| Connect a private Rose staff vault for local agents | Private staff vault |
| Start backend services | Backend setup |
| Start a frontend | Frontend development servers |
| Create an isolated database | Supabase preview setup |
| Prepare local or preview test data | Supabase seeding |
| Load dedicated chatbot CLI credentials | Per-CLI secrets |
| Set up Stripe billing for an environment, or verify the payment flow | Self-serve billing |
Testing¶
| Task | Procedure |
|---|---|
| Choose local services, cloud preview, diagnostics and chat evidence for a knowledge change | Testing knowledge changes |
| Run Python unit/integration tests and configure credentials | Backend testing |
| Verify knowledge ingestion, tenant isolation and retrieved passages | Knowledge change verification |
| Run frontend tests, type checks, and handle worker cleanup | Frontend testing |
| Check that a change to workspaces, roots, routing or the backoffice selector broke no legacy, alias or path-rooted client | Workspace non-regression checks |
| Get a test conversation to show in the backoffice Conversations list | Seeing a test conversation |
| Key a backoffice screen by workspace or open a Config Studio route for a path-rooted workspace | Client backoffice development |
| Test a PR's backend/knowledge in the cloud before merge | Cloud PR preview |
| Retrain a live client's knowledge in test (e.g. new website scraping), then copy it to production | Test-to-production knowledge migration |
| Evaluate chatbot responses | Evaluation examples |
| Check a skill, website-agent prompt or proposed FAQ on the deployed agent, or list a client's FAQs, without backend secrets (cloud session, Night Shift) | Prompt preview with rose |
| Run the Rose for Agents connector against the fake vendor | r4a local run |
| Test R4A buyer sign-in and vendor-account ownership end to end | r4a local run (just e2e-auth) |
| Set up a client (vendor) for Handover claimable accounts, or turn the broker on in an environment | Set up a vendor for Handover; Turn on the hosted broker |
Test the Handover claim (claimable accounts: broker, consent page, a vendor's MCP and OAuth, get_access, KMS signing) end to end, local to production, including a real Claude Code agent journey before merging |
Test the Handover claim end to end |
Change, release or bump the R4A vendor SDK (inboundx/rose-vendor-sdk, used by Ibanly) |
Change the vendor SDK |
| Run Rose itself as an R4A vendor end to end (sign-up, crawl, trial quota) | Rose as a vendor, isolated |
| Test the Ibanly buyer journey on the test connector from a Claude Code without MCP (website prompt, or found as an alternative) | Test it as a buyer |
| Compare model accuracy and latency | Model benchmarking |
Database changes¶
| Task | Procedure |
|---|---|
| Choose a database and apply a schema change | Supabase workflows |
| Apply a deliberate operator production push and reconcile Git | Operator production pushes |
| Inspect an existing function, view, or table | Inspect existing objects |
| Write migrations that also work on a fresh database | Migration authoring and replay |
| Give a table or column a new name without renaming it | Alias views over renamed concepts |
| Regenerate frontend database types | Generated types after migrations |
| Recover missing local migration history | Externally applied history |
| Run a heavy refresh or index build | Operator procedures |
| Turn on or check the periodic offsite backups of Supabase and MongoDB | Set up the periodic backups |
| Restore Supabase or MongoDB from the offsite backup (data loss, drill), including rebuilding the vector search indexes | Restore from the offsite backup |
Change the R4A buyer project (r4a-buyers, not the Rose project) |
Buyer identity; hosted setup in backend/apps/r4a_buyers/README.md |
Debugging¶
| Task | Procedure |
|---|---|
| Repair Night Shift bootstrap, Linear access or hotspot scan failures | Night Shift runner setup |
| Find dev-server logs or replay an authenticated API request | Local logs and authentication |
| Choose a chat test environment and check client knowledge freshness | Chat environment preflight |
| Reproduce a chatbot conversation | Chat CLI examples |
| Diagnose retrieval initialization failures | Retrieval troubleshooting |
| Diagnose frontend startup or rendering problems | Frontend troubleshooting |
| Diagnose database login, permissions, or missing seed data | Supabase debugging |
| Inspect production logging and adjust verbosity | Logging and production debugging |
| Diagnose a failed or stuck HubSpot sync, or re-run one | HubSpot sync operations |
Releases¶
| Task | Procedure |
|---|---|
| Prepare a PR or merge a feature | Development workflow |
| Run merge/release checks and follow deployment | Merge workflow |
| Build and release backend services | Backend release management |
| Deploy a frontend | Frontend deployment |
Client operations¶
| Task | Procedure |
|---|---|
| Finish a client's GEO FAQ custom subdomain or subdirectory (reverse proxy) setup | GEO custom hosting (staff) |
| A client's setting changed by itself or its values vanished: find who saved it and restore the last good version | Restore an overwritten client config |
Documentation maintenance¶
| Task | Procedure |
|---|---|
| Preview and build the documentation site | Local documentation development |
| Maintain the public model list generated at docs build time | Generated AI model inventory |
| Update the public cookie list after a widget storage or provider change, or on the monthly check | Public cookie list |
| Create or simplify agent instructions and their linked procedures | Maintaining AGENTS.md and shared procedures |
| Hand an installed-skill defect to its upstream coding agent | Upstream skill defects |
| Add or update a glossary term, or its class diagram | Maintaining the glossary |
When adding a procedure, update its existing guide and add a task link here. Write
for both people and agents: prerequisites → steps → expected result → verification.
Link directly to it from the nearest applicable AGENTS.md. Keep architecture
explanations and reference inventories in their existing topic pages.
When the backoffice can do a step, give that path first and the CLI as the
alternative, after checking the step is allowed in that environment: apptest
refuses knowledge writes while it targets shared Supabase (_test_knowledge_write_guard),
except for a client held for a test migration.