Skip to content

Commit a351134

Browse files
midagedevclaude
andcommitted
docs: teach the two axes, not the one word
SKILL.md is the file an agent reads before it writes anything, and its "Which origin you are talking to" section taught the coarse question. It now teaches both: which tracker (jira | linear | gadak) and where it runs (local | remote), with the paired workspace named as the case worth remembering — gadak, remote, no Atlassian credential anywhere. `kind` is still documented, as the older field to fall back on when a gadak is too old to send the pair. That section also said the durable file is `origin/issuetap.yaml`. It has been `.db` since the persist migration; the sentence was simply stale. README (both), CONCEPT, MIRROR, INSTALL, CONFIGURATION, NETWORK, FAQ, RECIPES, AGENT_SETUP, SECURITY, the specs, the site and this repo's own CLAUDE.md follow. `docs/decisions/` and CHANGELOG do not: those are history, and history is not revised. The `standalone-jira:` / `standalone-confluence:` id prefixes in data-model.md stay exactly as they are — they are stored bytes, not vocabulary. GDK-1282 (epic GDK-1278). Gates: go, doc-checks. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 26aaae8 commit a351134

26 files changed

Lines changed: 152 additions & 137 deletions

CLAUDE.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,19 +8,19 @@ hard-won 목록)와 `AGENTS.md`(스키마·쿼리)가 원본이다.
88

99
- **미러는 버려도 되는 캐시.** 원본은 항상 Jira — 그 Jira가 Atlassian
1010
Cloud든, gadak이 함께 들고 다니는 아주 미니멀한 셀프호스트 Jira
11-
(`issuetap`, standalone 워크스페이스)든. 어느 쪽이든 미러는 origin에서 다시
11+
(`issuetap`, gadak origin)든. 어느 쪽이든 미러는 origin에서 다시
1212
만들 수 있고, **gadak 자신은 원본을 보관하지 않는다.** gadak에만 존재하는
1313
원본 데이터를 만드는 변경은 금지 — 예외는 `local.db`(방문·검색 기록)와
1414
저장된 뷰이고, 그것들은 export 가능해야 한다.
15-
- **영속은 origin의 몫이다.** standalone 워크스페이스의 영속 공간은
15+
- **영속은 origin의 몫이다.** gadak origin 의 영속 공간은
1616
issuetap의 persist 파일이며 미러가 아니다. 그래서 백업 대상은 `gadak.db`
1717
아니라 그 파일이고, **워크스페이스는 origin 하나에 묶인다** — origin을
1818
바꾸는 것은 설정 편집이 아니라 새 워크스페이스다. 이 조항을 어기는 것이
1919
"다른 트래커를 조용히 가리키게 하는" 부류의 결함이다.
2020
- **쓰기는 전부 origin(Jira)을 통과**한 뒤 미러 갱신. 미러에 직접 쓰는 API를
2121
열지 않는다. 위키도 같은 규칙이다 — 페이지 쓰기(생성·편집·코멘트,
2222
GDK-380/381/382)는 origin.Wiki를 통과한다: connected는 Confluence REST,
23-
standalone은 issuetap의 Confluence API(미러 직접 쓰기가 아니다).
23+
gadak origin 은 issuetap 의 Confluence API(미러 직접 쓰기가 아니다).
2424
- **아웃바운드 없음.** 텔레메트리 금지. 나가는 요청은 사용자가 설정한
2525
origin(Atlassian 사이트·Linear: api.linear.app/uploads.linear.app), GitHub
2626
릴리스 버전 체크(설정으로 끔), 페어링한 home serve, loopback뿐

README.ko.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,8 @@ gadak은 Jira *그리고* Confluence를 로컬 SQLite 파일 하나로 미러링
3737

3838
연결된 사이트에는 [API 토큰](https://id.atlassian.com/manage-profile/security/api-tokens)
3939
하나가 필요합니다. 토큰 하나가 같은 사이트의 Jira와 Confluence를 모두
40-
커버합니다. Standalone 워크스페이스는 Atlassian 계정 자체가 필요 없습니다.
40+
커버합니다. origin 이 gadak 자신의 트래커인 워크스페이스는 Atlassian 계정이
41+
아예 필요 없습니다.
4142

4243
**무엇을 미러링할지는 직접 고릅니다.** 위키는 요청하기 전까지 꺼져 있고,
4344
켤 때는 스페이스를 지정합니다(`gadak init --spaces ENG,PROD`, 또는
@@ -79,7 +80,8 @@ gadak serve
7980
```
8081

8182
트래커를 떠날 때는 데이터를 들고 나옵니다 — 이슈·코멘트·전체 이력·첨부·
82-
위키 페이지가 동기화된 워크스페이스에서 standalone 워크스페이스로 옮겨지고,
83+
위키 페이지가 동기화된 워크스페이스에서 gadak 이 직접 보관하는 워크스페이스로
84+
옮겨지고,
8385
끝에 원본 대 이전본 건수 대조표가 출력됩니다:
8486

8587
```bash
@@ -216,10 +218,10 @@ macOS 앱에서는 같은 설치가 버튼이기도 합니다. **설정 → 연
216218

217219
## 무엇을 커버하나
218220

219-
Connected는 Atlassian Cloud와 대화합니다. Standalone(0.16부터) Atlassian
221+
Connected는 Atlassian Cloud와 대화합니다. gadak 자신의 트래커(0.16부터) Atlassian
220222
계정이 없는 워크스페이스입니다. 그 origin은 앱과 함께 다니는 미니멀한
221223
Jira입니다. 어느 쪽이든 미러는 캐시이고, 모든 쓰기는 origin을 통과합니다.
222-
Standalone에서 영속 파일은 origin의 persist 파일, 즉 워크스페이스 origin
224+
gadak origin 에서 영속 파일은 origin의 persist 파일, 즉 워크스페이스 origin
223225
폴더의 `issuetap.db`(SQLite, WAL)입니다. gadak이 꺼져 있을 때 복사하거나
224226
(`-wal`/`-shm` 사이드카 포함), `sqlite3 origin/issuetap.db ".backup
225227
dest.db"`를 쓰세요.
@@ -231,7 +233,7 @@ Jira 알림함은 안 됩니다. 그 일은 Jira에 남습니다.
231233
<details>
232234
<summary>▶ 전체 매트릭스와 ✅마다 붙은 각주</summary>
233235

234-
| | Connected (Atlassian Cloud) | Standalone (0.16부터) |
236+
| | Connected (Atlassian Cloud) | gadak 자신의 트래커 (0.16부터) |
235237
| --- | :---: | :---: |
236238
| 이슈 읽기·검색 (FTS, JQL, SQL) | ✅¹ | ✅¹ |
237239
| 생성, 코멘트, 상태 전이, 담당자, 라벨, 우선순위 |||
@@ -423,7 +425,7 @@ JQL로 여전히 물을 수 없는 것은 `gadak sql`과
423425
## 설치
424426

425427
brew 두 줄은 이 페이지 맨 위에 있습니다. Atlassian Cloud에 연결하거나,
426-
(0.16부터) Atlassian 계정이 필요 없는 standalone 워크스페이스로 시작합니다.
428+
(0.16부터) Atlassian 계정이 필요 없는 gadak origin 워크스페이스로 시작합니다.
427429
connected 사이트는
428430
[API 토큰](https://id.atlassian.com/manage-profile/security/api-tokens) 하나면
429431
되고, 그 토큰이 같은 사이트의 Jira와 Confluence를 함께 커버합니다.

README.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ stays the source of truth.
3535
</p>
3636

3737
A connected site needs one [API token](https://id.atlassian.com/manage-profile/security/api-tokens)
38-
— it covers Jira and Confluence on the same site. A standalone workspace
38+
— it covers Jira and Confluence on the same site. A workspace whose origin is gadak's own tracker
3939
needs no Atlassian account at all.
4040

4141
**You pick what it mirrors.** The wiki is off until you ask for it, and when
@@ -77,7 +77,7 @@ gadak serve
7777
```
7878

7979
Or leave one, data in hand — issues, comments, full history, attachments,
80-
and wiki pages move from a synced workspace into a standalone one, ending
80+
and wiki pages move from a synced workspace into a gadak-origin one, ending
8181
with a source-vs-migrated count table:
8282

8383
```bash
@@ -210,10 +210,10 @@ open-by-key half.
210210

211211
## What's covered
212212

213-
Connected talks to Atlassian Cloud. Standalone (from 0.16) is a workspace
213+
Connected talks to Atlassian Cloud. gadak's own tracker (from 0.16) is a workspace
214214
with no Atlassian account — a minimal Jira origin that travels with the
215215
app. The mirror is a cache either way; every write goes through the origin.
216-
On standalone the durable file is the origin's persist file — issuetap.db
216+
On a gadak origin the durable file is the origin's persist file — issuetap.db
217217
in the workspace's origin folder (SQLite, WAL). Copy it while gadak is not
218218
running (include the `-wal`/`-shm` sidecars), or
219219
`sqlite3 origin/issuetap.db ".backup dest.db"`.
@@ -225,7 +225,7 @@ dashboards and Jira's notification inbox do not — those stay in Jira.
225225
<details>
226226
<summary>▶ The full matrix, with the footnote for every ✅</summary>
227227

228-
| | Connected (Atlassian Cloud) | Standalone (from 0.16) |
228+
| | Connected (Atlassian Cloud) | gadak's own tracker (from 0.16) |
229229
| --- | :---: | :---: |
230230
| Issue read and search (FTS, JQL, SQL) | ✅¹ | ✅¹ |
231231
| Create, comment, transition, assignee, labels, priority |||
@@ -416,7 +416,7 @@ and its off switch.
416416
## Install
417417

418418
The two brew lines are at the top of this page. Atlassian Cloud, or (from
419-
0.16) a standalone workspace with no Atlassian account — a connected site
419+
0.16) a workspace whose origin is gadak's own tracker with no Atlassian account — a connected site
420420
needs one [API token](https://id.atlassian.com/manage-profile/security/api-tokens),
421421
which covers Jira and Confluence on the same site.
422422

SECURITY.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -181,7 +181,7 @@ device. A DNS-named Host — the shape `tailscale serve` forwards — is
181181
rejected by the rebinding guard unless the request is bound for a surface a
182182
token authenticates, and there are exactly three of those:
183183

184-
- **The origin passthrough** (`/api/v1/origin`, standalone workspaces): raw
184+
- **The origin passthrough** (`/api/v1/origin`, gadak-origin workspaces): raw
185185
REST for paired gadak machines and this machine's own routed writes
186186
(`internal/server/origin_rest.go`).
187187
- **The mirror REST** (any workspace kind): everything the local web UI
@@ -374,12 +374,12 @@ Offboarding depends on what the profile holds. On a connected workspace —
374374
or a paired one — the origin is elsewhere (your Atlassian site, or the home
375375
serve you paired with), and `rm -rf ~/.gadak` is the whole story: it removes
376376
the mirror, the credential, and every profile, and nothing else on the
377-
machine or in Jira knows gadak existed. On a standalone workspace that
377+
machine or in Jira knows gadak existed. On a workspace whose origin is gadak's own tracker that
378378
command destroys the origin itself: each profile's `origin/issuetap.db` is
379379
the only copy of that tracker anywhere. Copy the file out first (plain
380380
SQLite — nothing of gadak's is needed to read it) unless you mean to throw
381381
the data away. To offboard one profile rather than the whole home,
382-
`gadak workspaces rm <name>` removes just that profile; a standalone one
382+
`gadak workspaces rm <name>` removes just that profile; a gadak-origin one
383383
additionally requires `--destroy-origin`, for exactly the reason above.
384384

385385
## Release artifacts

contrib/omarchy/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ that answers one question offline: how much of the local gadak mirror is
55
open, and how much of that has been sitting in the same status for more
66
than seven days.
77

8-
This is not a “my assigned tickets” widget. A standalone workspace has no
8+
This is not a “my assigned tickets” widget. A workspace whose origin is gadak's own tracker has no
99
account (`gadak init --local` clears `AccountID`), and the competing
1010
community plugins (`tmn73.jira`, Linear, Todoist, ClickUp, `37signals.basecamp`)
1111
all need a cloud token and a live network. This one runs `gadak sql --json`

docs/AGENT_SETUP.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ machine already uses. Steps:
4040
## No Jira on this machine
4141

4242
If there is no Atlassian account and the user wants a backlog (this repo,
43-
this machine, an agent-owned plan), that is a **standalone** workspace — not
43+
this machine, an agent-owned plan), that is a workspace with a **gadak origin** — not
4444
a missing Jira token. Do not invent `TODO.md` or a GitHub Issue when `gadak`
4545
is on PATH. If this machine already has a connected gadak workspace, use a
4646
dedicated `--workspace` so personal issues never land on the company site.
@@ -49,7 +49,7 @@ Paste this prompt:
4949

5050
```text
5151
This machine has no Jira account. Keep a backlog for the work we do: create
52-
a gadak standalone workspace, file the first tickets, and show them to me.
52+
a gadak gadak-origin workspace, file the first tickets, and show them to me.
5353
5454
1. Install gadak if missing: `brew install midagedev/tap/gadak-cli`
5555
(or the install script in the repo README).
@@ -99,7 +99,7 @@ Jira issues are mirrored to a local SQLite file. Prefer these over any Jira API:
9999
the Jira-site escape hatch; `gadak views open` is open-in-gadak.
100100
- `gadak comment <KEY> -m "…"`, `gadak transition <KEY> "<status>"` — writes go
101101
through the origin (Jira on a connected workspace, the local origin on a
102-
standalone one).
102+
gadak-origin one).
103103

104104
Rules: filter on `status_category` ('new'|'inprogress'|'done') and ids, never
105105
on display names — Jira localizes those per account. Query the `issues_full`

docs/ARCHITECTURE.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ flowchart TB
4040
Confluence is a peer source (`internal/confluence`, `decisions/0006-confluence-connector.md`):
4141
page writes (create, edit, page comments — [GDK-380]/381/382) go through
4242
`origin.Wiki`, never the SQLite mirror. On a connected workspace that client
43-
is Confluence REST; on a standalone workspace it is the in-process issuetap
43+
is Confluence REST; on a workspace whose origin is gadak's own tracker it is the in-process issuetap
4444
handler (same session as `origin.Client`), whose Confluence API receives the
4545
same verbs.
4646

docs/CONCEPT.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ product than this one.
4242
**The mirror is disposable.** If the schema is a cache of the origin's truth,
4343
deleting it is always safe. That property is worth protecting: the moment the
4444
mirror holds something irreplaceable it becomes infrastructure someone has to
45-
back up. On standalone, the irreplaceable file is not `gadak.db` — it is the
45+
back up. On a gadak origin, the irreplaceable file is not `gadak.db` — it is the
4646
origin persist file (below).
4747

4848
## Two origins
@@ -52,7 +52,7 @@ A workspace is bound to one origin.
5252
- **Connected** — Atlassian Cloud (or Linear, when configured) is the record.
5353
The token talks to that site. Delete the profile directory and you have lost
5454
a cache.
55-
- **Standalone** (from 0.16) — the origin is an in-process minimal Jira
55+
- **A gadak origin** (from 0.16) — the origin is an in-process minimal Jira
5656
(`issuetap`). There is no Atlassian account. The durable file is
5757
`origin/issuetap.db` in the profile directory (`internal/origin/origin.go`
5858
`PersistRel`): a SQLite database (WAL). That is the file to back up —
@@ -132,7 +132,7 @@ CLI covers those plus `create`, `attach`, and `edit` (values always come from
132132
what the origin allows, never free text — an issue type or priority the CLI
133133
cannot match is refused with the names that origin actually uses).
134134
Wiki page create, edit, and comment go through the origin too — Confluence
135-
Cloud on a connected workspace, the in-process origin on standalone.
135+
Cloud on a connected workspace, the in-process origin on a gadak origin.
136136

137137
Hierarchy is first-class: `epic_key` is derived honestly (the nearest epic
138138
*ancestor*, so a sub-task groups under its epic, not its story), group-by-epic
@@ -175,7 +175,7 @@ Not a Jira replacement — we do not reimplement boards, dashboards, or the rest
175175
of Jira's UI; we contain those pages so the window can hold what the mirror
176176
refuses to model. Not a sync engine. Not an archive. Not multi-user. On a
177177
connected workspace, not a place to put anything you cannot afford to lose
178-
(the Atlassian site holds the record). On standalone, `origin/issuetap.db`
178+
(the Atlassian site holds the record). On a gadak origin, `origin/issuetap.db`
179179
*is* the record — losing that file loses the work.
180180

181181
## Good fit / bad fit

docs/CONFIGURATION.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -459,9 +459,9 @@ is nothing to say, and a client-supplied value is ignored.
459459
| `confluence` | object or absent | absent = wiki mirror off. `gadak init --local` writes the block scoped to `LOC` | Settings → Sources / `gadak config set confluence` | Next Confluence pass |
460460
| `linear` | object or absent | absent = Linear source off. `apiKey` (personal API key, sent bare in the Authorization header) turns the source on; writes to Linear-owned keys route through it | edit `config.json` (no Settings surface yet) | Next `sync --source linear` |
461461
| `linear.teamIds` | string[] | `[]` = every team the key can see; team UUIDs restrict the mirror scope | edit `config.json` | Next Linear pass |
462-
| `devStatus` | bool | **false** | `gadak config set devStatus true` / `config.json` (not on Settings UI or Settings PUT) | Next sync; connected Cloud: mirror Jira's development-status API into `dev_links` (one extra request per issue). Standalone always fetches; `gadak dev link` / `dev scan` write the same table |
463-
| `actor` | object or absent | absent = no acting identity; env `GADAK_ACTOR` (`slug\|display name`) overrides, and Claude Code sessions are auto-detected when both are unset | `gadak config set actor 'slug\|display name'` / `config.json` (not on Settings UI or Settings PUT; never team-exported) | Next origin session; writes to an issuetap origin (standalone/paired) carry `X-Issuetap-Actor` and attribute to that agent account. Never sent to connected Jira/Linear |
464-
| `locale` | string | _(empty)_ = English; `en` \| `ko` \| `ja` \| `de` | `gadak config set locale ko` / `config.json` (not on Settings UI or Settings PUT) | Standalone only: the origin's display-name language — status / issue-type / field names and agent aliases follow it; priority names stay English, like a live Cloud site. Changing it rebuilds the mirror on the next sync (display names are cached). A connected workspace ignores it: its language is the Atlassian account's |
462+
| `devStatus` | bool | **false** | `gadak config set devStatus true` / `config.json` (not on Settings UI or Settings PUT) | Next sync; connected Cloud: mirror Jira's development-status API into `dev_links` (one extra request per issue). A gadak origin always fetches; `gadak dev link` / `dev scan` write the same table |
463+
| `actor` | object or absent | absent = no acting identity; env `GADAK_ACTOR` (`slug\|display name`) overrides, and Claude Code sessions are auto-detected when both are unset | `gadak config set actor 'slug\|display name'` / `config.json` (not on Settings UI or Settings PUT; never team-exported) | Next origin session; writes to a gadak origin (local or paired) carry `X-Issuetap-Actor` and attribute to that agent account. Never sent to connected Jira/Linear |
464+
| `locale` | string | _(empty)_ = English; `en` \| `ko` \| `ja` \| `de` | `gadak config set locale ko` / `config.json` (not on Settings UI or Settings PUT) | A gadak origin only: the origin's display-name language — status / issue-type / field names and agent aliases follow it; priority names stay English, like a live Cloud site. Changing it rebuilds the mirror on the next sync (display names are cached). A connected workspace ignores it: its language is the Atlassian account's |
465465
| `confluence.spaces` | string[] | `[]` = every *global* space; personal spaces only if named (`internal/config/config.go`) | Settings → Sources / `gadak config set confluence.spaces` | Next Confluence pass |
466466
| `terminal` | `{shell, workingDir, scrollback, cursorBlink}` | absent = all defaults (see below) | `gadak config set terminal` or `terminal.<leaf>` (not on Settings UI or Settings PUT; never team-exported — shell and workingDir are this machine's paths) | Next terminal session create; a block set replaces the whole object, a leaf set merges |
467467

@@ -652,7 +652,7 @@ into `fields`.
652652
watches, favorites, and recents (`cmd/gadak/export.go`; help in
653653
`cmd/gadak/help.go`). Credentials never appear in the file — a credential-shaped
654654
string is refused (`secretscan`). It is not a `gadak team export` file (team
655-
settings live in that other command) and it does not include the standalone
655+
settings live in that other command) and it does not include the gadak-origin
656656
persist file (`origin/issuetap.db`) or the issue rows in `gadak.db`.
657657

658658
`gadak import <FILE>` restores those four lists. On a name/key conflict the
@@ -717,8 +717,8 @@ against `/myself` before anything is written.
717717
| --- | --- |
718718
| `$GADAK_HOME/config.json` or `~/.gadak/config.json` | Settings + credential (0600) |
719719
| `$GADAK_HOME/gadak.db` | SQLite mirror (a cache; the next sync rebuilds it from the origin) |
720-
| `$GADAK_HOME/origin/issuetap.db` | Standalone origin persist (`internal/origin/origin.go` `PersistRel`). SQLite (WAL); this is the record on a standalone workspace. Copy while gadak is not running (include `-wal`/`-shm`), or `sqlite3 <db> ".backup"`. Absent on a connected workspace. A sibling `origin/issuetap.yaml` is a one-shot seed if the db is missing. |
721-
| `~/.gadak/profiles/<name>/` | Isolated config + mirror (and, on standalone, persist) per profile |
720+
| `$GADAK_HOME/origin/issuetap.db` | A gadak origin's persist file (`internal/origin/origin.go` `PersistRel`). SQLite (WAL); this is the record on a workspace whose origin is gadak's own tracker. Copy while gadak is not running (include `-wal`/`-shm`), or `sqlite3 <db> ".backup"`. Absent on a connected workspace. A sibling `origin/issuetap.yaml` is a one-shot seed if the db is missing. |
721+
| `~/.gadak/profiles/<name>/` | Isolated config + mirror (and, on a gadak origin, persist) per profile |
722722

723723
Never write issue rows into the DB by hand — the next sync overwrites them. The
724724
supported external write table is `enrichments` (see [PLUGINS.md](PLUGINS.md)).

0 commit comments

Comments
 (0)