Read Me First

A plain-language introduction to the Notebook Collaboration Platform. If this is the first thing you have opened, you are in the right place. There is no code here and no technical shorthand — just what this software is, who it is for, and how to use it.

One thing to know up front: this is a core build. Everything described below genuinely works, but the product carries no visual styling or branding. It is a working foundation meant to be shaped into something that looks and feels like it belongs to your organisation.

---

1. Who this is for

This platform is built for teams who analyse data together. In practice that means:

• Data analysts and data scientists who write and run analysis, and who currently send files back and forth or take turns editing.
• Analytics and data science team leads who need to see what their team produced, who changed what, and whether the numbers in a report are current.
• Machine learning practitioners who build models and want their experiments kept in order rather than scattered across laptops.
• The people who receive the results — finance managers, product managers, executives — who do not write analysis themselves but need to read the outcome.

You do not need to be a software developer to use it. You do need to be comfortable with the idea of a notebook: a document where you write a piece of analysis and see its result immediately underneath.

2. What it does

It gives a team one shared place to write, run, review, schedule, and publish data analysis.

Several people can work in the same document at the same time and see each other's changes as they happen, in the way they might in a shared word processor. Every saved version is kept, so you can always see what an analysis looked like last week and what changed since. Analysis can be set to re-run on its own overnight or weekly, turning a one-off investigation into a standing report. And when a result is worth sharing, you can publish the parts that matter as a simple read-only page for colleagues who should see the outcome without touching the workings.

3. The domain

The field this software serves is data analysis and data science — the everyday work of taking an organisation's data and turning it into answers.

The dominant tool in this world is the notebook. A notebook interleaves short pieces of analysis with the results they produce, so the reasoning and the evidence sit side by side. This is why analysts favour them over spreadsheets for serious work: a notebook shows how a number was reached, not merely the number.

The long-standing standard for these documents is Jupyter, and Jupyter notebooks are saved in a widely understood file format. Jupyter is powerful, but it was designed for one person working alone. Teams built habits around that limitation — emailing files, maintaining "final_v3" copies, discovering too late that two people edited the same analysis. Meanwhile a number of commercial products fixed the collaboration problem but require you to keep your data and work inside their service, on their terms.

This platform sits deliberately in the gap between those two worlds: the openness and portability of Jupyter, with the collaboration, history, scheduling, and assistance that teams actually need day to day.

4. Where it fits

The organisations that use it. One installation serves a single organisation. Inside it, teams are separated into workspaces, and each workspace holds projects, which in turn hold notebooks. A company might give its marketing analytics team one workspace and its research team another, with some people belonging to both in different capacities.

The people who use it. Typically a mix: a handful of people writing analysis, a lead reviewing it, and a wider group who only ever read published results.

The systems around it. The platform is designed to sit alongside the tools you already have rather than replace them:

• Jupyter and the wider notebook ecosystem. Notebooks here use the standard format, so you can bring existing work in and take your work out at any time. Nothing you create is trapped.
• Your databases and data warehouses. Analysis can query your existing data stores directly rather than working from exported copies.
• Your own scheduling and automation. Other systems can trigger a notebook run from outside, so a run can be made part of a larger process you already operate.
• Your identity provider. Sign-in uses your organisation's existing login system, so people use the accounts they already have.

Two points of honesty about the current state. Some capabilities are complete underneath but have no screens yet: connecting to your own databases, version control commits against a code repository, and comment threads on a notebook are all available to automated systems but cannot yet be done by clicking. And the AI assistance described later requires a key from an AI provider to be configured before it will respond.

5. First run

The very first thing to do is look around the sample data.

The evaluation copy of the software starts up already populated: two example teams, a handful of projects, nine notebooks with real-looking analysis and results, published dashboards, saved version histories, and a record of past runs. Nothing you do to it can be lost, because the sample data is rebuilt fresh every time the software starts.

So open it and explore without caution. Click into a workspace, then a project, then a notebook. Read a notebook from top to bottom and notice how the analysis and its results alternate. Look at the panels beside it showing version history, scheduling, and publishing. Open one of the published dashboards to see what a colleague would receive.

Only once the shape of the thing makes sense is it worth connecting your own data.

6. Setting up

Setting up a real working environment happens in roughly this order. The precise commands live in the companion documents listed further down; this is the shape of the job.

1. Decide where it runs. It can be run on your own machines or hosted. For a first look, the self-contained evaluation copy needs nothing but a working container system.
2. Connect your sign-in system. Point the platform at your organisation's existing identity provider so colleagues sign in with their normal accounts. Until this is done, only the evaluation copy is usable.
3. Create your teams. Set up a workspace per team, then invite colleagues and give each the role that matches what they should be able to do — see the roles section below.
4. Organise the work. Within a workspace, create projects that reflect how your team actually divides its work, rather than one bucket for everything.
5. Bring in existing analysis. Existing Jupyter notebooks can be imported directly, so a team can start from work it already has instead of a blank page.
6. Connect your data. Point the platform at the databases your analysis needs to read. As noted above, this currently requires help from whoever administers the installation, because there is no screen for it yet.
7. Enable AI assistance, if you want it. This needs an account with an AI provider and a key configured by your administrator. Everything else works without it.

7. Day to day

Once set up, a typical week looks like this.

Writing analysis. Open a project and create a notebook, or open an existing one. Add pieces of analysis one after another. You can write in two languages: the general-purpose one most analysts use, and the query language used to ask questions of databases directly. Both can live in the same notebook, so you can pull data with a query and then work on it further without switching tools.

Running it. Each piece of analysis can be run on its own, with its result appearing directly beneath. You can also run a whole notebook at once. Every run is recorded, with its outcome and the time it happened, so there is always an answer to "when was this last current?"

Working with colleagues. Several people can open the same notebook together. You will see who else is present, each marked in their own colour, and their changes appear as they type. There is no locking, no taking turns, and no overwriting each other's work.

Reviewing changes. Save a version whenever you reach a point worth remembering, with a short note about what changed. The history lists every version. You can compare any two, or ask for a plain-language summary of the difference — useful when reviewing a colleague's work and you would rather read a sentence than a technical comparison.

Getting help from the assistant. Beside each piece of analysis is an option to have the AI suggest an improvement. Because it can see the whole notebook — the data in play, its shape, and earlier results — its suggestions relate to your actual work rather than being generic. It can also draft the written explanation between sections, and flag when a result looks unusual compared with what came before.

Automating the routine. For anything that should happen regularly, give the notebook a schedule and it will re-run unattended. This is what converts a piece of analysis into a weekly report that is simply ready when people arrive.

Sharing results. When something is worth wider attention, choose just the parts that should be seen and publish them as a dashboard. It gets its own web address and can be opened without an account. Your working analysis stays private; only the chosen results are visible. You can also share a notebook itself with a specific colleague, or export it as a standard file to send anywhere.

8. Ongoing care

A few things deserve attention beyond daily use.

• Back up the database. Everything — notebooks, history, schedules, published results — lives in the platform's database. Whoever administers your installation should be backing it up on a schedule and, more importantly, should have confirmed that restoring from a backup actually works.
• Check that scheduled runs are still succeeding. A scheduled report that has been quietly failing is worse than no report, because people keep trusting the last good numbers. Look over the run history periodically for failures.
• Review who has access. People change teams and leave. Revisit workspace membership every few months and remove access that is no longer appropriate.
• Retire published dashboards you no longer stand behind. A published dashboard stays reachable by anyone holding its address until it is removed. If a result is superseded, take it down rather than leaving it to be found and believed.
• Tidy up old versions and runs. Version history and run records accumulate indefinitely. Over years this grows, and periodically clearing out what no longer has value keeps things manageable.
• Keep the software updated. Updates bring fixes, including security fixes. Your administrator should apply them on a regular cadence rather than only when something breaks.

---

Glossary

Terms you will meet, in plain words.

Term	What it means
Notebook	A document made of numbered blocks, where each block is either a piece of analysis or a written note, and results appear directly beneath the analysis that produced them.
Cell	One of those blocks. Cells hold analysis, a database query, or plain text.
Output	The result a cell produced when it last ran — a number, a table, a chart, or a message.
Kernel	The engine that actually runs a cell and hands back the result. Mostly invisible; you notice it when it is busy or needs restarting.
Workspace	A team's area. Holds projects, and controls who has access.
Project	A grouping of related notebooks inside a workspace.
Version	A saved snapshot of a notebook, with a note about what changed.
Run	One occasion on which a notebook was executed, whether started by a person or by a schedule.
Schedule	A standing instruction to re-run a notebook automatically at set times.
Dashboard	A published, read-only page showing chosen results from a notebook, viewable without an account.
Presence	The indicator showing who else is currently in a notebook with you.
Role	What a person is permitted to do in a workspace: view, edit, or administer.

The other documents here

Everything else in this folder, and who each item is for.

Document	Who it is for	What it covers
getting-started.md	Anyone new, including non-developers	A short orientation and the steps to run the platform on your own machine.
production-initialization.md	Whoever administers the installation	Preparing a fresh staging or live deployment for first use.
api-reference.md	Developers connecting other systems	The full catalogue of automated entry points, for integration work.
useful-commands.md	Developers working on the software	Everyday commands needed while developing.
testing.md	Developers and reviewers	How the software is tested and why it is tested that way.
openapi.yaml, openapi.json	Developer tools	A machine-readable description of the same entry points as the API reference.
website/	Anyone evaluating the product	A self-contained overview page you can open in a browser.
store-thumbnail.png	Listing and catalogue use	The product's thumbnail image.

Also worth knowing about, outside this folder: docs/walkthrough-screenshots/ holds a narrated tour of the interface, screen by screen. It is the quickest way to see what the software looks like without running it.

Who can do what

Access is granted per workspace, so the same person can hold different roles in different teams — leading one and contributing to another.

Role	Can do
Viewer	Read notebooks and their results, and open published dashboards. Cannot change anything.
Editor	Everything a viewer can, plus create and edit notebooks, run them, save versions, set schedules, and publish dashboards.
Admin	Everything an editor can, plus manage the workspace itself — who belongs to it and what role each person holds.

If someone should see results but never alter the analysis behind them, make them a viewer. If they only ever need the published outcome, they need no account at all.

The sample data, and starting fresh

The evaluation copy arrives already populated so that every screen has something meaningful on it. It contains:

• Two example teams — one focused on business analytics, one on research.
• Four projects spread across them, covering areas like growth, product usage, and financial forecasting.
• Nine notebooks with realistic analysis and results already in place, in both supported languages.
• Eight people in various roles, so the sharing and permission behaviour is visible.
• Three published dashboards you can open as an outside viewer would.
• Saved version histories, schedules, and a record of past runs.

Starting fresh is automatic. Unless it has been deliberately set up to keep its data, the evaluation copy rebuilds this sample content from scratch every time it starts. Stop it and start it again and you are back to a clean, fully populated state. This makes it safe to experiment: change anything, delete anything, and a restart undoes it.

The corollary matters too — work you do in the evaluation copy is not permanent. It is for trying the software out, not for real analysis. When you are ready to keep things, set up a proper installation.

Common questions

Is my work locked into this platform? No. Notebooks use the standard Jupyter format and can be exported at any time, opening normally in Jupyter and other tools.

Can I use notebooks I already have? Yes. Existing Jupyter notebooks can be imported directly.

Do the people reading my published results need accounts? No. A published dashboard opens for anyone with its address. Bear that in mind when deciding what to publish — an address can be forwarded.

What happens if two of us edit the same thing simultaneously? Both edits are kept, and each of you sees the other's as it happens. This is the normal way to work here, not a problem to avoid.

Why does the AI assistant not respond? It needs a key from an AI provider, configured by whoever administers the installation. Every other feature works without it.

Why does the interface look so plain? Because this is a core build, deliberately. The functionality is complete; the visual design is intentionally left for you to make your own.

I cannot find comments, database connections, or version-control commits. Those work underneath but have no screens yet. They are reachable by automated systems, and your administrator can help in the meantime.

A number in a published dashboard looks out of date. Check the notebook's run history. A dashboard shows results from the last successful run, so if a schedule has been failing, the figures will be stale.

Where to get help

This software was generated by AI as part of the worlds-biggest-software-project initiative, and the community there is the place to go.

Come to wbsp.ai to ask questions, make suggestions about what this should do next, or find people who can adapt it for your organisation — whether that means applying your branding, adding features specific to how you work, or connecting it to systems particular to your industry.

While you are there, browse what others have built. Many community members have produced their own versions of this platform and of quite different applications, and one of them may already be much closer to what you need than a fresh start would be.