Organised on Diátaxis. Four kinds of page, two audiences.
Administrator — you run a deployment. You use the console, the CLI, and the environment. Developer — you change the code.
| Learning | Doing | Looking up | Understanding |
|---|---|---|---|
| Tutorial | How-to | Reference | Explanation |
| You are | Read |
|---|---|
| New administrator | Administering Insights |
| New contributor | Local development |
| Deploying for the first time | Deploy Insights |
| Looking for a setting | Configuration |
Learning by doing. Follow start to finish.
| Page | For |
|---|---|
| Administering Insights | Administrator |
| Local development | Developer |
One goal each. Assume you know what you want.
| Page | Goal | For |
|---|---|---|
| Get admin access | Sign in and gain administrator rights | Admin |
| Register an account | Add a platform account and its credential | Admin |
| Add a resource | Put a repository or model under collection | Admin |
| Issue a service token | Let a deployed service post its own metrics | Admin |
| Rotate the signing keyset | Roll the webhook signing key with no downtime | Admin |
| Manage administrators | Grant and revoke administrator access | Admin |
| Deploy Insights | Stand up and operate a deployment | Both |
| Run collection immediately | Collect now instead of waiting | Both |
| Diagnose a collection failure | Work out why metrics stopped | Both |
| Embed the dashboard | Put the dashboard in an iframe | Both |
| Set up the dashboard toolchain | Angular, the MCP server, and the llms-full.txt files |
Dev |
| Add a collector | Collect from a new platform | Dev |
| Add a queue or worker | Introduce a new named queue | Dev |
| Add a secret provider | Store credentials somewhere else | Dev |
| Run the tests | Get the suite passing locally | Dev |
Facts. Look things up; do not read start to finish.
| Page | Contains | For |
|---|---|---|
| Admin console | Every console screen, with screenshots | Admin |
| Configuration | Every environment variable | Both |
| CLI | Every command and flag | Both |
| HTTP API | Routes, guards, status codes, conventions | Both |
| Collection schedule | What is collected, when, from where | Both |
| Data model | Tables, fields, enumerations | Dev |
| just recipes | Every recipe in both justfiles | Dev |
| Invariants | Rules a change must not break | Dev |
| Test suite | What the 195 tests cover | Dev |
| Glossary | Project vocabulary | Both |
Why the system is shaped the way it is.
| Page | Explains |
|---|---|
| Architecture | The parts and how they fit |
| Metric collection | Gauges, rolling windows, retention |
| Watermarks | Why totals are not double counted |
| Authentication | Two credential paths, one guard |
| Queues and scheduling | One scheduler, many workers |
| Secret providers | Why credentials sit behind an interface |
| The dashboard | How the Angular application is served |
| Decisions | Eight architecture decision records |
#icicle-insights# #Reference# #Administrator# #Developer# #documentation-index#