154 lines
3.8 KiB
Markdown
154 lines
3.8 KiB
Markdown
# 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.
|