Updating

An update brings an existing project up to a newer release. Core, extensions and the hooks package update together.

1. Download the new familiar-workspace-<version>.zip from the Releases page. Also download the newer zip of each extension and of the hooks package, if you use them.

2. Put the zips in your project’s _update/ folder. Do not unzip them.

3. Open your agent in the project and run /ili-system-settings update ($system-settings on Codex).

   → verify: it lists what will change for each package, and what it will leave alone.

4. Answer yes to apply the update.

   → verify: it reports applied and a backup folder under 5-System/_update-backups/.

5. Start a new session. Nothing from the new release is live until then. You can then delete the zips from _update/.

What it keeps. The updater keeps:

• your content folders
• your own notes below the <!-- familiar:end --> marker in CLAUDE.md, AGENTS.md and GEMINI.md
• every familiar file you edited (reported as diverged)

Files that a release no longer includes move into the backup, so nothing is deleted. To roll back, copy the contents of the backup folder over the project.

Extensions. Each extension with a zip in _update/ updates in the same run. An extension without a zip stays as it is. If the new core version is outside the range that extension declares, the report warns you. An extension built from familiar-template has a release manifest after its author runs check_extension.py --release. To update an extension without a manifest, copy its folders onto the project again.

If the report starts with STOP, nothing was written. A different state-schema means a migration. Read the release notes in CHANGELOG.md first. A missing manifest means that you update by hand.

From a terminal

python .familiar/scripts/update.py --project . --from _update            # report only
python .familiar/scripts/update.py --project . --from _update --apply    # back up, then write

The updater in a 1.0.0 project has no --from option. For that one update, unzip the new release outside the project and run its copy of the updater:

python "<new familiar-workspace folder>/.familiar/scripts/update.py" --project "<your project>"

Add --extension "<folder>" for each extension, and --apply to write.

Format notes in tracker files

tasks.md, timeline.md, _knowledge-index.md, _abbreviations.md and 2-Drafts/_draft-index.md start with format notes. These notes sit beside your data, so no update replaces them. The rules live in .familiar/core/state-schema.md, which every update brings. If a release’s notes say that a table’s columns changed, compare the notes by hand.

Updating by hand

This method starts a new folder from the release and moves your content into it. It does not replace files inside your existing project. Nothing is deleted until you choose, so it cannot fail halfway. If you stop at any step, the old folder stays exactly as it was.

1. Download the new release and unzip it as a new folder, as in Getting started. Do not unzip it into or over your existing project folder.
2. Open both .familiar-project files (old project and new folder) and compare their state-schema: lines. If they differ, stop here. That is a schema migration, not a routine update, and this method does not do one. Read CHANGELOG.md and the release notes on the GitHub Releases page, or ask for help.
3. If your project has extensions, copy each one from its own download onto the new folder, the same way you added it the first time.
4. Copy these five folders from the old project into the new one, and replace the new copies: 1-Inputs/, 2-Drafts/, 3-Knowledge/, 4-Trackers/, 5-System/. Copy them, do not move them. The old folder is your rollback until you have tested the new one. Also copy any of your own agent settings, custom skills or hook settings that you want to keep.
5. Put back the new release’s copy of every _about.md (one per folder, including the root one) and of 3-Knowledge/_page-template.md. Step 4 replaced them with the old copies. These files hold no project data, so you lose nothing, and their wording stays current.
6. If you added your own instructions to CLAUDE.md, AGENTS.md or GEMINI.md, they are below the <!-- familiar:end --> marker. Copy those lines to the same place in the new folder’s file. Everything above the marker belongs to the release and comes with it.
7. In the new folder’s .familiar-project, replace only the created: line with the line from your old .familiar-project. Do not change its familiar-version: and state-schema: lines.
8. Open your agent in the new folder and start a new session. The agent reads skills, subagents and entry files when a session starts, so nothing from the new release is live until then.

Keep the old folder unchanged until you know that the new one works. It is your only rollback. When you are sure, archive or delete it yourself. familiar does not do this step.