Skip to content

Commit 467fc87

Browse files
parlakisikparlakisik
committed
docs: add CLI reference for connect, serve --shared, and hub
New pages: connect.md (register, subscribe, sync, publish, listen, status), serve.md (shared hub, daemon, cluster modes), hub.md (status, peer, stepdown). Updated agent docs with --include-shared flag and Tier 6-8 budget tiers. Updated CLI index with new command entries. Signed-off-by: Murat Parlakisik <parlakisik@gmail.com>
1 parent 41bbef4 commit 467fc87

5 files changed

Lines changed: 215 additions & 1 deletion

File tree

‎docs/cli/connect.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
# / ctx: https://ctx.ist
3+
# ,'`./ do you remember?
4+
# `.,'\
5+
# \ Copyright 2026-present Context contributors.
6+
# SPDX-License-Identifier: Apache-2.0
7+
8+
title: Connect
9+
icon: lucide/link
10+
---
11+
12+
## `ctx connect`
13+
14+
Connect to a shared context hub for cross-project knowledge sharing.
15+
Projects publish decisions, learnings, and conventions to a centralized
16+
hub; other projects receive them alongside local context.
17+
18+
### `ctx connect register`
19+
20+
One-time registration with a shared hub. Requires the hub address and
21+
admin token (printed by `ctx serve --shared` on first run).
22+
23+
```bash
24+
ctx connect register localhost:9900 --token ctx_adm_7f3a...
25+
```
26+
27+
On success, stores an encrypted connection config in
28+
`.context/.connect.enc` for future RPCs.
29+
30+
### `ctx connect subscribe`
31+
32+
Set which entry types to receive from the hub. Only matching types
33+
are returned by sync and listen.
34+
35+
```bash
36+
ctx connect subscribe decision learning
37+
ctx connect subscribe decision learning convention
38+
```
39+
40+
### `ctx connect sync`
41+
42+
Pull matching entries from the hub and write them to
43+
`.context/shared/` as markdown files with origin tags and date
44+
headers. Tracks last-seen sequence for incremental sync.
45+
46+
```bash
47+
ctx connect sync
48+
```
49+
50+
### `ctx connect publish`
51+
52+
Push entries to the hub. Specify type and content as arguments.
53+
54+
```bash
55+
ctx connect publish decision "Use UTC timestamps everywhere"
56+
```
57+
58+
### `ctx connect listen`
59+
60+
Stream new entries from the hub in real-time. Writes to
61+
`.context/shared/` as entries arrive. Press Ctrl-C to stop.
62+
63+
```bash
64+
ctx connect listen
65+
```
66+
67+
### `ctx connect status`
68+
69+
Show hub connection state and entry statistics.
70+
71+
```bash
72+
ctx connect status
73+
```
74+
75+
## Shared files
76+
77+
Entries from the hub are stored in `.context/shared/`:
78+
79+
```
80+
.context/shared/
81+
decisions.md # Shared decisions with origin tags
82+
learnings.md # Shared learnings
83+
conventions.md # Shared conventions
84+
.sync-state.json # Last-seen sequence tracker
85+
```
86+
87+
These files are read-only (managed by sync/listen) and never
88+
mixed with local context files.
89+
90+
## Agent integration
91+
92+
Include shared knowledge in agent context packets:
93+
94+
```bash
95+
ctx agent --include-shared
96+
```
97+
98+
Shared entries are included as Tier 8 in the budget-aware
99+
assembly, scored by recency and type relevance.

‎docs/cli/hub.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
# / ctx: https://ctx.ist
3+
# ,'`./ do you remember?
4+
# `.,'\
5+
# \ Copyright 2026-present Context contributors.
6+
# SPDX-License-Identifier: Apache-2.0
7+
8+
title: Hub
9+
icon: lucide/network
10+
---
11+
12+
## `ctx hub`
13+
14+
Manage a running shared context hub cluster.
15+
16+
### `ctx hub status`
17+
18+
Show cluster status: role, entry count, and connected projects.
19+
20+
```bash
21+
ctx hub status
22+
```
23+
24+
### `ctx hub peer`
25+
26+
Add or remove peers from the cluster at runtime.
27+
28+
```bash
29+
ctx hub peer add host2:9901
30+
ctx hub peer remove host2:9901
31+
```
32+
33+
### `ctx hub stepdown`
34+
35+
Transfer leadership to another node gracefully. Use before
36+
taking a node offline for maintenance.
37+
38+
```bash
39+
ctx hub stepdown
40+
```

‎docs/cli/index.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ own guards and no-op gracefully.
5959
| [`ctx learning`](context.md#ctx-learning) | Manage `LEARNINGS.md` (reindex) |
6060
| [`ctx journal`](recall.md#ctx-recall) | Browse and export AI session history |
6161
| [`ctx journal`](recall.md#ctx-journal) | Generate static site from journal entries |
62-
| [`ctx serve`](recall.md#ctx-serve) | Serve any zensical directory (default: journal site) |
62+
| [`ctx serve`](serve.md#ctx-serve) | Serve journal site or shared context hub |
6363
| [`ctx watch`](tools.md#ctx-watch) | Auto-apply context updates from AI output |
6464
| [`ctx setup`](tools.md#ctx-hook) | Generate AI tool integration configs |
6565
| [`ctx loop`](tools.md#ctx-loop) | Generate autonomous loop script |
@@ -80,6 +80,8 @@ own guards and no-op gracefully.
8080
| [`ctx hook`](tools.md#ctx-hook) | Manage lifecycle hooks (shell scripts for automation) |
8181
| [`ctx skill`](tools.md#ctx-skill) | Manage reusable instruction bundles |
8282
| [`ctx config`](config.md#ctx-config) | Manage runtime configuration profiles |
83+
| [`ctx connect`](connect.md#ctx-connect) | Connect to a shared context hub |
84+
| [`ctx hub`](hub.md#ctx-hub) | Manage hub cluster (status, peer, stepdown) |
8385
| [`ctx system`](system.md#ctx-system) | System diagnostics and hook commands |
8486

8587
---

‎docs/cli/init-status.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@ ctx agent [flags]
101101
| `--format` | md | Output format: `md` or `json` |
102102
| `--cooldown` | 10m | Suppress repeated output within this duration (requires `--session`) |
103103
| `--session` | (none) | Session ID for cooldown isolation (e.g., `$PPID`) |
104+
| `--include-shared` | false | Include shared hub entries from `.context/shared/` |
104105

105106
**How budget works**:
106107

@@ -112,6 +113,9 @@ in priority tiers:
112113
3. **Conventions**: all conventions, up to 20% of budget
113114
4. **Decisions**: scored by recency and relevance to active tasks
114115
5. **Learnings**: scored by recency and relevance to active tasks
116+
6. **Steering**: applicable steering file bodies
117+
7. **Skill**: named skill content (from `--skill`)
118+
8. **Shared**: hub entries from `.context/shared/` (with `--include-shared`)
115119

116120
Decisions and learnings are ranked by a combined score (how recent + how
117121
relevant to your current tasks). High-scoring entries are included with

‎docs/cli/serve.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
# / ctx: https://ctx.ist
3+
# ,'`./ do you remember?
4+
# `.,'\
5+
# \ Copyright 2026-present Context contributors.
6+
# SPDX-License-Identifier: Apache-2.0
7+
8+
title: Serve
9+
icon: lucide/server
10+
---
11+
12+
## `ctx serve`
13+
14+
Serve a journal site locally, or start the shared context hub.
15+
16+
### Static site (default)
17+
18+
```bash
19+
ctx serve # Serve .context/journal/site/
20+
ctx serve ./my-site # Serve a specific directory
21+
```
22+
23+
### Shared context hub
24+
25+
Start a gRPC hub server for cross-project knowledge sharing.
26+
27+
```bash
28+
ctx serve --shared # Start on default port 9900
29+
ctx serve --shared --port 8080 # Custom port
30+
ctx serve --shared --data-dir /path/to/data # Custom data directory
31+
```
32+
33+
On first run, generates an admin token and prints it to stdout.
34+
Save this token — it's needed for `ctx connect register`.
35+
36+
**Default data directory:** `~/.ctx/hub-data/`
37+
38+
### Daemon mode
39+
40+
Run the hub as a background process:
41+
42+
```bash
43+
ctx serve --shared --daemon # Start in background
44+
ctx serve --stop # Stop the running daemon
45+
```
46+
47+
The daemon writes a PID file to `<data-dir>/hub.pid`.
48+
49+
### Cluster mode
50+
51+
For high availability, run multiple hubs with Raft leader election:
52+
53+
```bash
54+
ctx serve --shared --port 9900 --peers host2:9901,host3:9901
55+
```
56+
57+
Raft is used only for leader election. Data replication uses
58+
sequence-based gRPC sync (append-only, no conflicts).
59+
60+
### Flags
61+
62+
| Flag | Description |
63+
|------|-------------|
64+
| `--shared` | Start the shared context hub |
65+
| `--port` | Hub listen port (default 9900) |
66+
| `--data-dir` | Hub data directory (default ~/.ctx/hub-data/) |
67+
| `--daemon` | Run hub in the background |
68+
| `--stop` | Stop a running hub daemon |
69+
| `--peers` | Comma-separated peer addresses for cluster mode |

0 commit comments

Comments
 (0)