# Project pack: Grist @ 2a1e3ce

Facts about **Grist** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Grist combines the ease of a spreadsheet with the structure of a database. Tables can link to each other, columns have types, formulas are Python, and you can build dashboards with charts and cards on top. It is good for inventories, trackers, small CRMs and family records.

## Version and source
- Repository: https://github.com/gristlabs/grist-core
- Pinned commit: `2a1e3ce9ef13fd562d086c84b03d4040077a78ae`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/gristlabs/grist-core/archive/2a1e3ce9ef13fd562d086c84b03d4040077a78ae.zip
- Official docs: https://support.getgrist.com
- Live demo: https://docs.getgrist.com/. The official hosted version, free for personal use. Don't enter private data in public documents.
- Licence: **Apache-2.0**. Free to use, change and share, even commercially. Keep the licence and copyright notices, and note your changes. It includes a patent licence.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/gristlabs/grist-core bespoke-grist
  cd bespoke-grist
  git checkout --detach 2a1e3ce9ef13fd562d086c84b03d4040077a78ae
  # Prepare development requirements and local configuration first.
  yarn install
  yarn run install:python
  yarn start
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name grist -p 8484:8484 -v grist-persist:/persist gristlabs/grist
  # then open http://localhost:8484
  ```

- Needs: Docker for a trial, Node 22 and Python 3.11 for development
- Develop: `yarn start`
- Test: `yarn test`
- Check/lint: `yarn lint`
- Stack: typescript, python (Express, Knockout, Pyodide, Yarn). Difficulty for a non-developer with an AI: **advanced**. A large TypeScript and Python code base with its own formula engine. Most customisation happens inside documents: tables, formulas, widgets and custom widgets. Source changes are rare.

## Customisation points (settings → extend → code)
- **tables-and-formulas** [settings]: Tables, types, links between tables and Python formulas. → `In a document, under Raw Data and column formulas`
- **pages-and-widgets** [settings]: Cards, charts, calendars and forms. → `In a document, under Add Page and Add widget`
- **access-rules** [settings]: Who sees which rows and columns. → `Document settings → Access rules`
- **custom-widgets** [extend]: Embed your own HTML widgets. → `Custom widget API (grist-plugin-api.js)`
- **api** [extend]: Read and write tables from scripts. → `REST API and the Python or JS client`
- **core** [code]: Changes to the product itself. → `app/client and app/server`

## Must keep working
- The document file format, so old documents keep opening.
- Access rules enforcement on the server.
- Python formula sandboxing.

## Staying updatable
Customise inside Grist documents. Fork only for product changes and keep them small, as the core moves quickly.

## Data, costs and safety
- Personal data: **yes**. Stored in: SQLite document files and a small home database under /persist. Every Grist document is one file. Back up the /persist folder.
- Service: Single sign-on provider (OIDC or SAML) (optional, depends on provider): Team logins on your own server.
- Setting `GRIST_SESSION_SECRET` (**secret**: the person enters it themselves, never in chat): Secret used to sign sessions. Never paste it into an AI chat.
- Setting `APP_HOME_URL`: The address people use to reach Grist when it is not localhost.
- Documents can contain private data. Set access rules before sharing.
- Formulas run code. Only open documents from people you trust.

---

# Customising Grist

With Grist, most customisation happens in documents, not code. This repo is for running your own server or changing the product.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Browser app | app/client/ |
| Server and API | app/server/ |
| Formula engine (Python) | sandbox/grist/ |
| Shared code | app/common/ |
| Plugins and widgets | plugins/ and static/ |
| Docker examples | docker-compose-examples/ |

## Use the gentlest change first

1. **Settings (no code):** tables, formulas, widgets, forms and access rules.
2. **Extend:** custom widgets and the REST API.
3. **Code:** the product itself, rarely.

## Recipes

- **Custom widget:** build a small web page that uses `grist-plugin-api.js`, host it, and add it as a Custom widget.
- **Script access:** create an API key in your profile settings and call the REST API from a script.

## Running and checking your changes

- `yarn start` and create a document with two linked tables.
- `yarn test` for the area you changed.
- Check access rules by opening the document as another user.

## Pitfalls

- Never commit API keys or the `/persist` folder.
- Formula changes affect existing documents. Test on copies.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/grist/2a1e3ce/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/grist/2a1e3ce/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/grist/2a1e3ce/r2/SKILL.md)