docs(development): add a code map for one observation's journey

[kingmakeruix]

What

A contributor-facing code map that follows one observation — a tree measured in the rain — from the form on a device, through local storage and push, into server storage, and back out through pull and export.

New page: docs/docs/development/observation-journey.md, registered in docs/sidebars.ts next to development/architecture.

It contains:

• a Mermaid sequence diagram of the happy path;
• a table of ten steps, each naming the responsible project and linking to the symbol that implements it;
• what changes when the device is offline (the write path makes no network call, and pending is derived from synced_at/updated_at rather than stored);
• why attachments are a separate pipeline (observation JSON holds a GUID-shaped basename, binaries move over /api/attachments and are tracked on their own cursor);
• five existing tests that exercise the path;
• a short list of what the map deliberately does not cover.

Verification

Every source link was opened and confirmed before it was written, and every symbol named in the table was checked to exist at the cited path. The Mermaid diagram was parsed with the same Mermaid version the docs site uses.

From docs/, which is exactly what the docs workflow runs:

npm ci
npm run test    # No critical errors
npm run build   # Generated static files

The validator's warnings are all pre-existing anchor warnings in other pages; this page adds none. The page is 619 words excluding code blocks.

One thing I did not resolve

The issue says to ask in the issue when two sources disagree, so I am flagging rather than silently picking a story.

docs/docs/reference/form-specifications.md L784 states:

New observations use the latest form version

The Formulus write path cannot currently do that:

1. PersistObservationInput has formType, finalData, observationId — no version field. submitObservation(formType, finalData) is positional, also with no version.
2. persistObservationWithAttachments L232 calls saveObservation({ formType, data: committedData }).
3. WatermelonDBRepo.saveObservation L225 then stores record.formVersion = input.formVersion || '1.0'.

So every locally created observation is persisted as '1.0', while formplayer does know the version — it reads formSchema.version for drafts and sticky fields, but never sends it across the bridge. This looks like the same root cause as #909, and I did not want to rewrite that documentation or claim a behaviour the code does not implement, so the page simply states that choosing a form's schema version is a separate question.

Closes #912

[najuna-brian]

Please comment on the issue so that it can be assigned to you

[kingmakeruix]

@najuna-brian Thanks — done. I have commented on #912 asking to be assigned, with a short summary of what the draft already contains and what I deliberately left out.

I will not push anything further to this branch until the issue is assigned to me, so the diff stays as reviewed.