# Section 0 Shared Docs -- 0.1.8

These documents are available in two ways:

1. Read the projected copy in AFFiNE.
   AFFiNE is the shared reading and whiteboard space. Markdown from this repo
   appears there as a read-only projection.

2. Edit them in Git.
   The editable files live in this plain Markdown repo. Use your normal editor,
   then commit and push changes.

If you want to change one of these docs, edit the Markdown file. Do not edit the
AFFiNE copy; it will be refreshed from Git.

## What To Edit

Edit Markdown files in this Git repo.

Current docs:

- `README.md`
- `docs/source-models.md`
- `rta/concept.md`
- `rta/reports/current-status.md`

## First-Time Setup

From any machine that can reach the private lab network:

```sh
curl -fsSL http://100.64.0.1:30087/section0/rta-handbook/raw/branch/main/scripts/setup-section0-docs.sh | sh
```

The script clones this repo into:

```text
~/Developer/Section0/rta-handbook
```

It also installs a small helper command at:

```text
~/.local/bin/section0-docs
```

Override the destination if you prefer:

```sh
TARGET_DIR=~/work/rta-handbook \
  curl -fsSL http://100.64.0.1:30087/section0/rta-handbook/raw/branch/main/scripts/setup-section0-docs.sh | sh
```

## Daily Flow

```sh
section0-docs auth login
section0-docs doctor
section0-docs pull

# Edit Markdown files in your normal editor.

section0-docs status
MESSAGE="Describe the doc change" section0-docs commit
section0-docs push
section0-docs wait
```

`section0-docs push` updates Git. By default it also waits until the projection
status says the pushed commit has reached AFFiNE. `section0-docs wait` can be
run again any time to check convergence.

## Personal Markdown Mounts

Use this when you want to share a selected local Markdown or Obsidian folder
without moving custody into the shared Git repo.

```sh
section0-docs auth login
section0-docs mount add research ~/Documents/Obsidian/Research
section0-docs mount list
section0-docs mount plan research
section0-docs mount sync research
section0-docs mount status research
```

The mount declaration is local to your machine. That is intentional: your
personal source files stay under your control. AFFiNE receives a read-only
derived copy.

To stop publishing that folder:

```sh
section0-docs mount unmount research
section0-docs mount remove research
```

## Contributor Setup

Anonymous clone/read works on the private lab network. Pushing requires
Authentik login through the helper.

Run this once per checkout:

```sh
section0-docs auth login
```

The login opens Authentik in your browser, configures the Git author from your
identity, and installs the repo Git credential. After that, normal Git tooling
works too.

Prove write access without changing `main`:

```sh
section0-docs push-test
```

`push-test` does not commit files and does not change `main`. It pushes the
current commit to a temporary scratch branch, then deletes that branch
immediately. If Git prompts for a password, use a Gitea access token rather
than your normal account password. If login is healthy, Git should usually get
the credential from your local credential store.

## End-To-End Smoke Test

Use this when setting up a new machine:

```sh
section0-docs pull

cd "$(section0-docs open)"
printf '\nMBP sync smoke test: %s\n' "$(date -Is)" >> rta/reports/current-status.md

section0-docs status
MESSAGE="MBP sync smoke test" section0-docs commit
section0-docs push
```

After projection completes, the smoke line should appear in:

```text
Agent Workspace / Section 0 / Git Projections / RTA Handbook / RTA Status
```

## Source Models

This repo is the shared Git model: shared docs are edited in Git, then copied
into AFFiNE for reading.

Personal vault mounts are different: a person keeps custody of their own local
Obsidian vault and only shares selected Markdown into AFFiNE. See
`docs/source-models.md` for that more advanced case.