Documentation Standard

This file defines how every automation in the Movement Tribe estate is documented. It is self-documenting: this page follows the same frontmatter schema it describes (see the block at the top), so a parser can read this file the same way it reads any automation doc.

The goal is one doc per automation, each doc both readable by a human in plain markdown and parseable by a machine. A given logical process (for example a sync that spans n8n and the DaySmart Business App suite) gets ONE doc per platform it touches, and every one of those docs shares a single canonical name.

1. Frontmatter schema

Every automation doc begins with a YAML frontmatter block. All fields below are required (use an empty list [] or empty string where a field does not apply, never omit the key).

Field	Type	Meaning
id	string	Short kebab-case unique id for this doc. Matches the filename without the .md.
name	string	The canonical name of the automation. This is the SAME verbatim string across every platform the automation lives on and across every doc that describes a piece of it. See section 3.
platform	enum	Where this piece runs. One of: n8n, businessapp, goteamup, postgres, meta, or another platform slug added as the estate grows.
status	enum	Lifecycle state. One of: live, draft, paused, deprecated.
triggers	list	What starts this piece. Each entry is a short string, for example "webhook: goteamup-customer-updated" or "webhook received". Empty list if this piece is a library or reference.
calls	list	Ids (or canonical names) of other automation docs this piece invokes downstream. Example: the n8n engine calls the suite applier.
called_by	list	Ids (or canonical names) of other automation docs that invoke this piece. The inverse of calls. Example: the suite applier is called_by the n8n engine.
credentials	list	Credential NAMES only, never secret values. Example: "n8n cred odUGMC6NZNAKlkQh (GoTeamUp M2M)". See section 6.
data_stores	list	Databases, tables, or persistent state this piece reads or writes. Example: "postgres mirror.field_mirror_state".
linked_docs	list	Filenames of related docs (both directions), so a reader can navigate the whole process.

Example frontmatter

---
id: goteamup-suite-field-sync-n8n
name: "GoTeamUp → Suite: Field Sync"
platform: n8n
status: live
triggers:
  - "webhook: goteamup-customer-updated"
calls:
  - goteamup-suite-field-sync-suite
called_by: []
credentials:
  - "n8n cred odUGMC6NZNAKlkQh (GoTeamUp M2M token)"
  - "n8n cred TAZ5cYldQx0U4vAw (Mirror Postgres)"
data_stores:
  - "postgres mirror.field_mirror_state"
  - "postgres mirror.watched_fields"
linked_docs:
  - goteamup-suite-field-sync-suite.md
---

2. Body structure

After the frontmatter, every doc uses these sections in this order. Keep headings exactly as written so docs are consistent and skimmable.

1. Plain-English summary: two to four sentences. What this does and why it exists, no jargon. A non-technical reader should understand the point.
2. How it works (step by step): the actual mechanics, in order. For an n8n workflow, one subsection or list item per node. For a suite automation, one per step. Name every node or step exactly as it appears in the tool.
3. Dependencies: credentials (by name), data stores, upstream and downstream automations, external APIs, and any wiring (for example a webhook destination registered on the source system).
4. Failure modes and gotchas: known traps, publish or deploy quirks, and anything that has bitten us before. Write these so future-you does not repeat the mistake.
5. Change log: newest entry at the top, one line each, format YYYY-MM-DD: what changed.

3. Naming convention

The canonical name is the backbone of this whole system. Rules:

• Format: GoTeamUp → Suite: <Thing>, using a real right-arrow character. <Thing> names the logical process, for example Field Sync.
• The canonical name is used VERBATIM in three places, and they must match character for character:
  1. the n8n workflow name,
  2. the suite (Business App) automation name,
  3. the name: field in every doc describing a piece of that process.
• Doc FILENAMES derive from the name plus a platform suffix: <kebab-of-name>-<platform>.md. Example: canonical name GoTeamUp → Suite: Field Sync gives goteamup-suite-field-sync-n8n.md and goteamup-suite-field-sync-suite.md.
• If a tool's UI still shows an old name (for example the suite automation currently reads "Inbound Marketing Preference" in the Business App UI), the doc records both: the canonical name: in frontmatter, and a note in the body stating the current UI label and that it is pending a rename. The canonical name always wins as the identifier.

4. Cross-platform rule

A single logical process often spans more than one platform. When it does:

• Each platform's piece gets its own doc, all sharing the one canonical name:.
• The docs cross-reference each other through calls, called_by, and linked_docs:
  • the upstream piece lists the downstream piece under calls,
  • the downstream piece lists the upstream piece under called_by,
  • both list each other under linked_docs.
• This makes the graph walkable in both directions from any doc. A reader (or a parser) can start at the n8n engine and follow calls to the suite applier, or start at the applier and follow called_by back.

5. How to add a new synced field

The architecture is one generic engine plus one generic applier, so adding a field is a data change plus a small mapping change, not a new workflow. To add a field:

1. Postgres: insert a row into mirror.watched_fields with the new field_key, the GoTeamUp gt_field_id, and active = true.
2. n8n (Build Changes node): add a mapping for the new field so it emits {external_id, field, value}. If the GoTeamUp raw value needs translating (as marketing_preference maps the choice strings to yes or no), add that translation here.
3. Suite applier: add a field branch in the applier so it knows which contact field to update for the new field value, and how.
4. Docs: update both the n8n doc and the suite doc (How it works, Dependencies, Change log) to reflect the new field. If the field adds a new data store or credential, update those frontmatter lists too.

No new workflow is created. The same webhook, the same change-detection logic, and the same POST path carry every field.

6. Credentials rule

Docs name credentials, they never contain secret values. Reference a credential by its stable id and a human label, for example n8n cred odUGMC6NZNAKlkQh (GoTeamUp M2M token). Secret values live only in their stores (n8n credential vault, env files on the relevant host) and are never pasted into a doc, a commit, or a change log.

Change log

• 2026-10-21: Standard created. Defined frontmatter schema, body structure, naming convention, cross-platform rule, add-a-field procedure, and credentials rule.