Educate & activate
Short sessions and habits that turn access into daily use.
Teach one habit: search first, record after
Everything else follows from one habit:
- Search first. Before acting, the agent searches your sources and the ledger, and cites what it finds.
- Record after. When the work ends, the agent records each decision or finding as its own topic. If a decision changes, a new topic supersedes the old one.
Give people a card to keep next to their editor:
text
Before: search the ledger and our sources. Follow accepted decisions. Cite what you use.
After: record each decision, incident, defect or dead end as its own topic.
Changed your mind? Record the new decision and supersede the old one. Never rewrite history.
Not sure it's worth recording? Ask: would the next person regret not knowing this?The agent instructions do most of the work. People mostly need to see the habit in action, and to trust it.
Run three short sessions
Keep each session to 30 minutes, on real work, with everyone using their own agent.
| Session | When | What happens | Done when |
|---|---|---|---|
| 1. Connect | Week 2 | Everyone creates a key, adds the config and runs a first search | Everyone has a cited answer |
| 2. Search first | Week 3 | Each person brings a real question, and the group checks the citations | Everyone has checked a citation |
| 3. Record after | Week 4 | Each person records a real decision or finding from this week, then finds it at the top of the Ledger page | Everyone has recorded a topic |
Session 1: connect
- Sign in to the console with Continue with GitHub.
- On API keys, in the Create a key panel, enter a label and select Create key. Copy the key.
- Set the key as
RAG_API_KEY. Select the team's namespace in the switcher at the top of the sidebar, then copy the config under Connect your agent into the project's.mcp.json. - Restart the agent, and ask the first question from the team's use cases.
Session 2: search first
Ask each person to run a real question, then open every citation in the answer. Show how the answer changes with a narrower search. These prompts are illustrative:
text
Search only the wiki for our refund policy, and cite the page.
Search the ledger for decisions about the export service, and list them with their status.Session 3: record after
Each person asks their agent to record something real from this week. Then one person shows a change of mind: they record a new decision that supersedes an old one, and the group opens both on the Ledger page. The old topic shows a "Superseded" notice that links to the new one.
Hold office hours
Run a weekly 30-minute slot, led by a champion. Invite people to bring:
- a question their agent answered badly;
- a topic they weren't sure how to record;
- a source that seems out of date.
Turn each good fix into a prompt on the team page.
Build the habit into work you already do
- Add a "Ledger topic" line to your pull request, incident and change templates.
- Start design reviews with an agent's search of the ledger for earlier decisions.
- Close an incident only when its topic is resolved and its root cause is recorded.
- When someone asks a question in chat, answer with a citation or a topic id.
Track who's active
For each person, track four steps: connected, first cited answer, first topic recorded, and use in real work this week. The Team page shows when each person's newest key was last used, which covers the first step. Measure & expand covers the rest.
Troubleshooting
| Symptom | What to do |
|---|---|
| Every call fails with 401 | The agent isn't receiving the key. On macOS, apps started from the Dock don't read shell profiles. Pass the key the way your client's guide shows, such as Claude Code. |
| Results come from the wrong team's material | Check the X-RAG-Namespace header. With no header, Workstate uses the oldest namespace you have access to. |
| A new document isn't found | Check the source's last sync on Sources, or select Sync now. Uploaded files change only when an admin uploads them. |
| A newly recorded topic isn't found | Search catches up within about 5 seconds. ledger_get finds the topic straight away. |
| The console says No namespace yet | Nobody has given the person a namespace yet. Ask an owner or admin to give them one in the Namespaces column on Team. |