Skip to content

Commit 93fa932

Browse files
isTravisisTravis
committed
Clean language
1 parent d8d4afe commit 93fa932

12 files changed

Lines changed: 138 additions & 144 deletions

File tree

‎src/routes/docs/api/accounts.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,14 +44,14 @@ export default function DocsApiAccounts() {
4444
<p>There are two authentication methods:</p>
4545
<ul>
4646
<li>
47-
<strong>Session cookies</strong> — set via OAuth2/PKCE sign-in through{' '}
47+
<strong>Session cookies</strong>: set via OAuth2/PKCE sign-in through{' '}
4848
<a href="https://auth.knowledgefutures.org" className="text-link hover:underline">
4949
KF Auth
5050
</a>{' '}
5151
(handled by better-auth at <code>/api/auth/*</code>), used by the web UI
5252
</li>
5353
<li>
54-
<strong>API keys</strong> — <code>Authorization: Bearer ul_...</code>, used by apps and
54+
<strong>API keys</strong>: <code>Authorization: Bearer ul_...</code>, used by apps and
5555
scripts
5656
</li>
5757
</ul>

‎src/routes/docs/api/collections.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -294,7 +294,7 @@ export default function DocsApiCollections() {
294294
<td>
295295
<code>422</code>
296296
</td>
297-
<td>No versions exist yet — push a version first before updating metadata.</td>
297+
<td>No versions exist yet. Push a version first before updating metadata.</td>
298298
</tr>
299299
</tbody>
300300
</table>
@@ -308,7 +308,7 @@ export default function DocsApiCollections() {
308308
<p>
309309
Fork a public collection into a target organization. Creates a new collection under the
310310
target org with the source's latest version. Records, schemas, and files are referenced
311-
(not copied) — zero additional storage.
311+
(not copied); zero additional storage.
312312
</p>
313313
<h3>Request</h3>
314314
<pre className="bg-ink text-parchment overflow-x-auto p-3 text-xs">

‎src/routes/docs/api/files.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ export default function DocsApiFiles() {
5656
<li>
5757
Reference it in records as <code>{fileRefInline}</code>
5858
</li>
59-
<li>Push your version — the server verifies all referenced files exist</li>
59+
<li>Push your version. The server verifies all referenced files exist</li>
6060
</ol>
6161

6262
<hr className="border-rule my-6" />
@@ -181,7 +181,7 @@ export default function DocsApiFiles() {
181181
<td>
182182
<code>400</code>
183183
</td>
184-
<td>Hash mismatch — the uploaded bytes don't match the hash in the URL.</td>
184+
<td>Hash mismatch: the uploaded bytes don't match the hash in the URL.</td>
185185
</tr>
186186
</tbody>
187187
</table>

‎src/routes/docs/api/index.tsx‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ export default function DocsApi() {
2424

2525
<h2>Authentication</h2>
2626
<p>
27-
All <code>GET</code> requests are <strong>public</strong> — no authentication required to
27+
All <code>GET</code> requests are <strong>public</strong>; no authentication required to
2828
read public data. All write requests (<code>POST</code>, <code>PATCH</code>,{' '}
2929
<code>PUT</code>, <code>DELETE</code>) require authentication.
3030
</p>
@@ -39,13 +39,13 @@ export default function DocsApi() {
3939
<p>Keys have three scopes:</p>
4040
<ul>
4141
<li>
42-
<code>read</code> — list and download data
42+
<code>read</code>: list and download data
4343
</li>
4444
<li>
45-
<code>write</code> — push versions, upload files
45+
<code>write</code>: push versions, upload files
4646
</li>
4747
<li>
48-
<code>admin</code> — delete collections, manage keys
48+
<code>admin</code>: delete collections, manage keys
4949
</li>
5050
</ul>
5151
<p>
@@ -65,7 +65,7 @@ export default function DocsApi() {
6565
<h3>Invalid Credentials</h3>
6666
<p>
6767
If a <code>Bearer</code> token is provided but does not match any key, the request is{' '}
68-
<strong>immediately rejected</strong> with <code>401</code> — it will not fall through to
68+
<strong>immediately rejected</strong> with <code>401</code>. It will not fall through to
6969
anonymous access.
7070
</p>
7171

@@ -99,13 +99,13 @@ export default function DocsApi() {
9999
<p className="mt-3">Every response includes rate limit headers:</p>
100100
<ul>
101101
<li>
102-
<code>X-RateLimit-Limit</code> — max requests in the current window
102+
<code>X-RateLimit-Limit</code>: max requests in the current window
103103
</li>
104104
<li>
105-
<code>X-RateLimit-Remaining</code> — requests remaining
105+
<code>X-RateLimit-Remaining</code>: requests remaining
106106
</li>
107107
<li>
108-
<code>X-RateLimit-Reset</code> — seconds until the window resets
108+
<code>X-RateLimit-Reset</code>: seconds until the window resets
109109
</li>
110110
</ul>
111111
<p>
@@ -133,28 +133,28 @@ export default function DocsApi() {
133133
<p>Common status codes:</p>
134134
<ul>
135135
<li>
136-
<code>400</code> — Bad request (invalid input)
136+
<code>400</code>: Bad request (invalid input)
137137
</li>
138138
<li>
139-
<code>401</code> — Authentication required or invalid credentials
139+
<code>401</code>: Authentication required or invalid credentials
140140
</li>
141141
<li>
142-
<code>403</code> — Insufficient permissions (wrong scope)
142+
<code>403</code>: Insufficient permissions (wrong scope)
143143
</li>
144144
<li>
145-
<code>404</code> — Resource not found
145+
<code>404</code>: Resource not found
146146
</li>
147147
<li>
148-
<code>409</code> — Version conflict (re-fetch and retry)
148+
<code>409</code>: Version conflict (re-fetch and retry)
149149
</li>
150150
<li>
151-
<code>413</code> — Payload too large (file upload exceeds size limit)
151+
<code>413</code>: Payload too large (file upload exceeds size limit)
152152
</li>
153153
<li>
154-
<code>422</code> — Validation error (e.g. missing files)
154+
<code>422</code>: Validation error (e.g. missing files)
155155
</li>
156156
<li>
157-
<code>429</code> — Rate limited (wait and retry)
157+
<code>429</code>: Rate limited (wait and retry)
158158
</li>
159159
</ul>
160160

@@ -165,26 +165,26 @@ export default function DocsApi() {
165165
<div>
166166
<Link to="/docs/api/accounts" className="text-link underline">
167167
Accounts
168-
</Link>{' '}
169-
— API keys, profiles
168+
</Link>
169+
: API keys, profiles
170170
</div>
171171
<div>
172172
<Link to="/docs/api/collections" className="text-link underline">
173173
Collections
174-
</Link>{' '}
175-
— create, list, update, delete
174+
</Link>
175+
: create, list, update, delete
176176
</div>
177177
<div>
178178
<Link to="/docs/api/versions" className="text-link underline">
179179
Versions
180-
</Link>{' '}
181-
— push snapshots, browse history, diff
180+
</Link>
181+
: push snapshots, browse history, diff
182182
</div>
183183
<div>
184184
<Link to="/docs/api/files" className="text-link underline">
185185
Files
186-
</Link>{' '}
187-
— upload and download content-addressed files
186+
</Link>
187+
: upload and download content-addressed files
188188
</div>
189189
</nav>
190190
</DocsLayout>

‎src/routes/docs/api/versions.tsx‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ export default function DocsApiVersions() {
107107
<p>
108108
Versions are the core of Underlay. Each version is an immutable snapshot of a collection:
109109
schema + records + file references. Pushing a new version uses the{' '}
110-
<strong>negotiate protocol</strong> — a three-step flow similar to git's pack negotiation.
110+
<strong>negotiate protocol</strong>, a three-step flow similar to git's pack negotiation.
111111
</p>
112112

113113
<hr className="border-rule my-6" />
@@ -284,7 +284,7 @@ export default function DocsApiVersions() {
284284
<td>
285285
<code>GET .../negotiate/:sessionId</code>
286286
</td>
287-
<td>Check session status — returns remaining needed records and files.</td>
287+
<td>Check session status. Returns remaining needed records and files.</td>
288288
</tr>
289289
<tr>
290290
<td>
@@ -303,7 +303,7 @@ export default function DocsApiVersions() {
303303
<code>400</code>
304304
</td>
305305
<td>
306-
Unexpected record hash — a submitted record doesn't match any needed hash, or the
306+
Unexpected record hash. A submitted record doesn't match any needed hash, or the
307307
batch is empty/malformed.
308308
</td>
309309
</tr>
@@ -318,8 +318,7 @@ export default function DocsApiVersions() {
318318
<code>409</code>
319319
</td>
320320
<td>
321-
Version conflict — someone pushed since your <code>base_version</code>.
322-
Re-negotiate.
321+
Version conflict. Someone pushed since your <code>base_version</code>. Re-negotiate.
323322
</td>
324323
</tr>
325324
<tr>

‎src/routes/docs/concepts.tsx‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,7 @@ export default function DocsConcepts() {
2424
<p>
2525
A <strong>collection</strong> (plural: <strong>collections</strong>) is a named, versioned
2626
body of structured data. It belongs to an account (a user or an organization) and is
27-
identified by <code>:owner/:slug</code> — for example,{' '}
28-
<code>knowledge-futures/pubpub-archive</code>.
27+
identified by <code>:owner/:slug</code>, e.g. <code>knowledge-futures/pubpub-archive</code>.
2928
</p>
3029
<p>
3130
A collection can be public (browsable by anyone) or private (visible only to the owner and
@@ -42,13 +41,13 @@ export default function DocsConcepts() {
4241
A <strong>JSON Schema</strong> describing the structure of the records
4342
</li>
4443
<li>
45-
A set of <strong>records</strong> — the actual data
44+
A set of <strong>records</strong> (the actual data)
4645
</li>
4746
<li>
48-
References to <strong>files</strong> — binary assets
47+
References to <strong>files</strong> (binary assets)
4948
</li>
5049
<li>
51-
A <strong>metadata</strong> bag — a JSON object that can contain <code>readme</code>,{' '}
50+
A <strong>metadata</strong> object that can contain <code>readme</code>,{' '}
5251
<code>license</code>, and other fields
5352
</li>
5453
</ul>
@@ -63,7 +62,7 @@ export default function DocsConcepts() {
6362
<li>Metadata-only changes (readme, license, etc.) → patch bump</li>
6463
</ul>
6564
<p>
66-
Each version also has a <strong>hash</strong> — a SHA-256 digest of the canonical
65+
Each version also has a <strong>hash</strong>, a SHA-256 digest of the canonical
6766
representation of the schema, records, and file references. Two versions with the same hash
6867
have identical content.
6968
</p>
@@ -98,7 +97,7 @@ export default function DocsConcepts() {
9897
</li>
9998
</ul>
10099
<p>
101-
Relationships between records are expressed as ID references — just strings. There are no
100+
Relationships between records are expressed as ID references (just strings). There are no
102101
joins, no foreign keys. An LLM or application can resolve references by reading the schema
103102
and records together.
104103
</p>
@@ -108,8 +107,8 @@ export default function DocsConcepts() {
108107
<code>strip_unknown_fields</code> to accept stripping them automatically.
109108
</p>
110109
<p>
111-
Binary data is referenced via <code>{fileRef}</code> — a pointer to a content-addressed file
112-
in the registry. The wire format for records is JSONL — one record per line, independently
110+
Binary data is referenced via <code>{fileRef}</code>, a pointer to a content-addressed file
111+
in the registry. The wire format for records is JSONL, one record per line, independently
113112
hashable and streamable.
114113
</p>
115114

@@ -128,10 +127,10 @@ export default function DocsConcepts() {
128127
<p>Underlay has two account types:</p>
129128
<ul>
130129
<li>
131-
<strong>Users</strong> — individual accounts with email/password login
130+
<strong>Users</strong>: individual accounts with email/password login
132131
</li>
133132
<li>
134-
<strong>Organizations</strong> — group accounts with members who have roles (owner, admin,
133+
<strong>Organizations</strong>: group accounts with members who have roles (owner, admin,
135134
member)
136135
</li>
137136
</ul>

‎src/routes/docs/index.tsx‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -22,21 +22,19 @@ export default function Docs() {
2222
<Link to="/docs/concepts" className="text-link underline">
2323
Concepts
2424
</Link>{' '}
25-
<span className="text-ink-muted text-xs">
26-
— Collections, versions, records, files
27-
</span>
25+
<span className="text-ink-muted text-xs">Collections, versions, records, files</span>
2826
</li>
2927
<li>
3028
<Link to="/docs/quickstart" className="text-link underline">
3129
Quickstart
3230
</Link>{' '}
33-
<span className="text-ink-muted text-xs">— Push your first version in 5 minutes</span>
31+
<span className="text-ink-muted text-xs">Push your first version in 5 minutes</span>
3432
</li>
3533
<li>
3634
<Link to="/docs/integration" className="text-link underline">
3735
Integration Guide
3836
</Link>{' '}
39-
<span className="text-ink-muted text-xs">— Push data from any app, no SDK</span>
37+
<span className="text-ink-muted text-xs">Push data from any app, no SDK</span>
4038
</li>
4139
</ul>
4240
</section>
@@ -48,32 +46,32 @@ export default function Docs() {
4846
<Link to="/docs/api" className="text-link underline">
4947
Overview
5048
</Link>{' '}
51-
<span className="text-ink-muted text-xs">— Auth, rate limits, error handling</span>
49+
<span className="text-ink-muted text-xs">Auth, rate limits, error handling</span>
5250
</li>
5351
<li>
5452
<Link to="/docs/api/accounts" className="text-link underline">
5553
Accounts
5654
</Link>{' '}
57-
<span className="text-ink-muted text-xs">— Signup, login, API keys</span>
55+
<span className="text-ink-muted text-xs">Signup, login, API keys</span>
5856
</li>
5957
<li>
6058
<Link to="/docs/api/collections" className="text-link underline">
6159
Collections
6260
</Link>{' '}
63-
<span className="text-ink-muted text-xs">— Create, list, update, delete</span>
61+
<span className="text-ink-muted text-xs">Create, list, update, delete</span>
6462
</li>
6563
<li>
6664
<Link to="/docs/api/versions" className="text-link underline">
6765
Versions
6866
</Link>{' '}
69-
<span className="text-ink-muted text-xs">— Push snapshots, browse history, diff</span>
67+
<span className="text-ink-muted text-xs">Push snapshots, browse history, diff</span>
7068
</li>
7169
<li>
7270
<Link to="/docs/api/files" className="text-link underline">
7371
Files
7472
</Link>{' '}
7573
<span className="text-ink-muted text-xs">
76-
— Upload and download content-addressed files
74+
Upload and download content-addressed files
7775
</span>
7876
</li>
7977
</ul>
@@ -86,7 +84,7 @@ export default function Docs() {
8684
<Link to="/docs/self-host" className="text-link underline">
8785
Self-hosting
8886
</Link>{' '}
89-
<span className="text-ink-muted text-xs">— Docker, Postgres, S3</span>
87+
<span className="text-ink-muted text-xs">Docker, Postgres, S3</span>
9088
</li>
9189
</ul>
9290
</section>
@@ -99,7 +97,7 @@ export default function Docs() {
9997
Protocol
10098
</Link>{' '}
10199
<span className="text-ink-muted text-xs">
102-
— Content-addressed data model, hashing spec, negotiate push/pull
100+
Content-addressed data model, hashing spec, negotiate push/pull
103101
</span>
104102
</li>
105103
</ul>

0 commit comments

Comments
 (0)