# Project pack: TiddlyWiki @ 999763a

Facts about **TiddlyWiki** 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.

> TiddlyWiki is a non-linear notebook made of small notes called tiddlers. The whole wiki, with its editor, can live in one HTML file that works offline, or run on a small Node.js server. Plugins, themes and a built-in macro language let you turn it into a journal, task list, recipe book or personal website.

## Version and source
- Repository: https://github.com/TiddlyWiki/TiddlyWiki5
- Pinned commit: `999763abb080adc68595dbee7526f315da28a044`. 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/TiddlyWiki/TiddlyWiki5/archive/999763abb080adc68595dbee7526f315da28a044.zip
- Official docs: https://tiddlywiki.com/#Documentation
- Live demo: https://tiddlywiki.com/. The documentation site is itself a TiddlyWiki, so you can try the editor right there.
- Licence: **BSD-3-Clause**. Free to use, change and share, even commercially. Keep the copyright notice, and do not use the authors' names to endorse your version.

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

  ```sh
  git clone https://github.com/TiddlyWiki/TiddlyWiki5 bespoke-tiddlywiki
  cd bespoke-tiddlywiki
  git checkout --detach 999763abb080adc68595dbee7526f315da28a044
  # Prepare development requirements and local configuration first.
  npm install
  node ./tiddlywiki.js ./editions/tw5.com-serve --listen
  ```

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
  npm install -g tiddlywiki
  tiddlywiki mywiki --init server
  tiddlywiki mywiki --listen
  # then open http://127.0.0.1:8080
  ```

- Needs: A browser for single-file use, or Node.js 20+ for the server version
- Develop: `node ./tiddlywiki.js ./editions/tw5.com-serve --listen`
- Test: `npm test`
- Check/lint: `npm run lint`
- Stack: javascript (TiddlyWiki widgets and wikitext, Node.js). Difficulty for a non-developer with an AI: **easy**. Most changes are new tiddlers: a stylesheet, a template or a small widget written in wikitext, with no build step. Changing the core engine is plain JavaScript.

## Customisation points (settings → extend → code)
- **tags-and-views** [settings]: Organise and view notes your way without any code. → `Tiddler tags, the Control Panel, saved filters`
- **stylesheet-and-theme** [extend]: Colours, fonts and layout. → `Tiddlers tagged $:/tags/Stylesheet, Control Panel → Appearance`
- **plugins** [extend]: Add calendars, kanban boards, search and publishing tools. → `Control Panel → Plugins, the plugins/ folder`
- **wikitext-templates** [extend]: Custom views for recipes, contacts or tasks. → `Tiddlers tagged for templates and the ViewTemplate, and macros`
- **core-and-widgets** [code]: New widgets, filters and editor features. → `core/modules/ and plugins/tiddlywiki/`

## Must keep working
- Save and backup behaviour (single-file saver and the Node.js filesystem syncer).
- Existing tiddler titles and fields, so links keep working.
- Core plugin compatibility when upgrading.

## Staying updatable
Put changes in your own tiddlers and plugins, not in the core. Then upgrading TiddlyWiki is as simple as swapping the empty edition.

## Data, costs and safety
- Personal data: **yes**. Stored in: One HTML file, or a folder of tiddler files when run with Node.js. Back up the HTML file or the wiki folder. Copying the file is a complete backup.
- A wiki file may contain private information. Don't share it publicly before checking.
- Third-party plugins run in your browser with full access to your wiki. Install only trusted ones.

---

# Customising TiddlyWiki

TiddlyWiki is easiest to make your own from inside the wiki: new notes (tiddlers) that hold styles, templates and macros. The source repository is only needed to change the engine itself.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Wiki engine (store, filters, parser) | core/modules/ and boot/ |
| Widgets and editor | core/modules/widgets/ and core/modules/editor/ |
| Shipped plugins | plugins/tiddlywiki/ |
| Themes and palettes | themes/ and core/palettes/ |
| Example editions | editions/ (start from editions/empty or editions/server) |
| Tests | editions/test/ |

## Use the gentlest change first

1. **Settings (no code):** palette, layout, tags and the Control Panel.
2. **Extend:** stylesheet, template and macro tiddlers, and plugins.
3. **Code:** JavaScript modules in the core or a custom plugin.

## Recipes

- **New stylesheet:** create a tiddler tagged `$:/tags/Stylesheet` with your CSS.
- **New view for a type of note:** make a template tiddler and attach it with a ViewTemplate tag and a filter.
- **New widget:** write a JavaScript module tiddler of type `application/javascript` and `module-type: widget`.

## Running and checking your changes

- `node ./tiddlywiki.js ./editions/test --verbose --version --build index` runs the test edition, or use `npm test`.
- Open your wiki in a clean browser profile to confirm it works with no extras.
- Download a fresh copy and check your notes survived.

## Pitfalls

- Changing a tiddler's title breaks links to it.
- Keep a backup copy of the HTML file before experimenting.

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