Skip to content
This page is also available as markdown at /docs/update/auto-update-folders-and-spaces.md. For the complete documentation index, see llms.txt.
Get started

Auto-update folders and Spaces

You do not have to turn on auto-update one document at a time. Turn it on for a folder, a Space, the Company space or every new document, and the documents inside follow that setting. A document can still have its own setting.

This page builds on Automatically update documents, which explains how Falconer updates a document when a pull request merges.

  • GitHub integration: repositories connected to Falconer, so merged pull requests can update your docs
  • Edit access: you need edit access to change a folder, a Space or a document. Only organization owners can change the Company space and the default for new documents.

Falconer checks these places in order and uses the first one that has a setting:

  1. The document’s own setting
  2. The nearest folder above the document, up to and including its Space
  3. The Company space, for documents in the Company space
  4. The default for new documents, if it was on when the document was created
  5. Off

The update mode follows the same order on its own. For example, a document can follow its Space for on or off and still use its own mode. When nothing sets a mode, the mode is Full self-driving.

Some documents are not reached by folder and Space settings:

  • Folders and documents whose sharing restricts editing. Settings from above stop at a folder whose sharing restricts editing, so set auto-update on that folder itself. A document whose own sharing restricts editing follows no folder at all. Turn auto-update on for it directly.
  • Documents in a private section. Auto-update does not run on private documents.
  • Files in the Files view that are not in the Docs view. Turn auto-update on from the file.

When you move a document, its own setting moves with it. A document that follows its folder picks up the setting of its new folder. Moving a document into a private section turns auto-update off for it.

When auto-update is off, a banner at the top of the folder or Space offers to turn it on.

Auto-update banner on a Space

To turn it on from the banner, use the toggle. To see all the options:

  1. Open the folder or Space.
  2. Click the more button (⋮) and select Details.
  3. Under Auto-update, turn on Enabled.
  4. Review the summary in the confirmation dialog, choose an Update mode and, for Review, add reviewers.
  5. Click Confirm.
Confirmation dialog when turning on auto-update for a Space

The confirmation dialog shows what the change does before anything changes:

  • How many documents will turn on, turn off or change mode
  • How many people will be notified
  • Documents that are not reached because their own sharing restricts editing
  • Files that are not included because they are not in the Docs view

Every change to a folder, a Space, the Company space or the default for new documents asks for this confirmation.

After you confirm, the Auto-update section of the Details panel shows the new setting.

Auto-update section of a Space after it is turned on

Documents that have their own setting keep it when you change the folder. To make them follow, select Also make N docs with an existing doc-level setting follow this folder-level setting in the confirmation dialog.

Confirmation dialog with the option to make documents follow the folder

You can also click Make them follow next to the document count in the Details panel.

The Auto-update section of a folder or Space shows:

FieldWhat it shows
EnabledWhether auto-update is on, and where the value comes from, for example From the Engineering Space or Set on this folder. Inherit instead (folder) or Use organization default (Space) removes the folder’s own setting.
Update modeFull self-driving or Review
ReviewersPeople who get auto-update notices and approve drafts in Review mode. Reviewers from a parent folder or Space are tagged Inherited.
DocsHow many documents follow this folder, how many have their own setting and how many are not reached
Auto-update section in the Details panel of a folder

A document that follows a folder or Space shows where its setting comes from. The banner at the top of the document and the Auto-update section in Details both show the source.

Banner on a document that inherits auto-update from its Space

To give a document its own setting, change Enabled or Update mode in its Details sidebar. To make it follow its folder again, click Use folder setting.

Auto-update section of a document that inherits from its Space

Anyone who can edit a document can change its auto-update setting. An organization owner who cannot edit a document can still turn auto-update off for it.

Organization owners can set defaults in Settings → Organization settings → Auto-update.

Auto-update section in organization settings
  • New documents org-wide: turns on auto-update for documents created in Falconer from now on that are shared with the organization. Existing, imported and synced documents do not change. A document keeps this setting from the day it was created, and a folder or Space setting takes priority over it.
  • Spaces: turns auto-update on or off for the Company space and for each Space, with its update mode and reviewers. You can change a Space if you can edit it. Only organization owners can change the Company space.

When you turn on New documents org-wide, you choose the update mode for new documents.

Confirmation dialog for the new documents default

The new documents default sets the mode only. Reviewers are chosen on each document, folder or Space.

ModeWhat happens
Full self-drivingFalconer applies updates directly. Owners and reviewers get a notice of what changed.
ReviewFalconer proposes drafts. Owners and reviewers approve or reject them.
  • The document owner is always a reviewer.
  • Add more reviewers on a document, a folder, a Space or the Company space. Reviewers of a folder or Space are reviewers of every document that follows it.
  • If a change turns on auto-update for a document that has nobody to notify, Falconer adds you as a reviewer.

The document Details sidebar has two sections called Reviewers. The one under Auto-update is for auto-update drafts. The other one asks coworkers to review the document itself and is not related to auto-update.

Owners and reviewers get these notifications. Each one goes to the inbox and to Slack by default, not to email. Change them in Settings → Personal settings → Notifications.

NotificationWhen you get it
Auto-update settings changedSomeone turns auto-update on or off, or changes its mode, for documents you own or review. You get one notice per change, with the documents it affects.
Added as an auto-update reviewerSomeone makes you a reviewer for a document, a folder or a Space. You do not get it when you add yourself.
Auto-applied document updatesFalconer applied an update to a document in Full self-driving mode.
Document drafts proposed by GitHub PRs and Document update digestFalconer proposed drafts that need your approval in Review mode. They come right away or in a digest, based on your organization’s notification cadence.

The person who makes a change does not get a notice about it.

A Space with a public docs site has an Auto-update history tab on its dashboard. It lists, newest first, the auto-update setting changes in the Space and the updates Falconer made: updates applied, drafts left for review and digests. Each entry shows who did it, what changed, which documents it affected and how many people were notified.

Auto-update history of a Space

You need edit access to the Space to see the history. It leaves out documents you cannot see.

For other Spaces, read the history from MCP, the API or the CLI.

Use auto-update from MCP, the API and the CLI

Section titled “Use auto-update from MCP, the API and the CLI”

Agents connected through MCP and scripts that use the API can make the same changes. Every folder, Space and organization change needs confirmed: true. Without it, nothing changes and the response is a preview of the change, so the agent can show it to you first.

TaskMCPAPI
Change a folderupdate_folderPATCH /folders/{folderId}
Change a Spaceupdate_spacePATCH /spaces/{spaceId}
Change a documentedit_settings with the document scopePATCH /docs/{id}/metadata
Change organization defaultsedit_settings with the org scopePATCH /settings/org
List or change reviewerslist_auto_update_approvers, update_auto_update_approversGET or PUT on /docs/{id}/approvers, /folders/{folderId}/approvers and /default-space/approvers
Read a Space’s historylist_auto_update_history, list_auto_update_history_documentsGET /spaces/{spaceId}/auto-update-history
  • autoUpdateEnabled takes true, false or null. null removes the folder’s own setting so it follows its parent.
  • autoUpdateMode takes auto_apply (Full self-driving), draft_approval (Review) or null. On a document, the mode field is docUpdateMode.
  • resetAutoUpdateOverrides: true makes the documents and subfolders inside follow the new setting.
  • Without confirmed: true, the API returns 409 with the code confirmation_required and the preview.

In the CLI (version 0.2.34 and later):

falconer folder update <folder-id> --auto-update on --mode review
falconer space update <space-id> --auto-update inherit --reset-overrides
falconer approvers <doc-id> --add <user>
falconer space history <space-id>

Without --yes, the CLI prints the preview and changes nothing. Run the same command again with --yes to apply it.