# OKFShare documentation

> A hosted service for publishing and retrieving versioned OKF Markdown knowledge bundles.

## Product scope

OKFShare accepts small Markdown knowledge bundles, validates their paths and
metadata, renders a readable share page, and stores immutable revisions. It is a
publishing and retrieval service, not an execution environment: references and
content in a bundle are treated as data.

## Publish and retrieve

1. Prepare a directory of safe, relative `.md` files and validate it.
2. Publish it with the CLI or `POST /api/v1/shares` using a workspace session,
   scoped API key, or authenticated CLI credential.
3. Receive a share ID and slug; the viewer route is `/s/:slug`.
4. Update the share to create a new immutable revision, or roll back by selecting
   an earlier revision.
5. Retrieve source files with the authenticated bundle endpoint, or use bounded
   search and context endpoints.

The product loop is `init`, `setup`, `doctor`, `validate`, `publish`,
`update` (alias `push`), `log`, `search`, `context`, `diff`, and
`rollback`. The CLI prints concise human-readable text by default (with
`next:` follow-up commands and error hints); pass `--json` for the machine
envelope. `npx okfshare@latest schema` returns the machine-readable command
tree.

## Publishing API

`POST /api/v1/shares` creates a share. It requires a workspace session or a
Bearer API key or CLI credential with the `workspace:write` scope. Send an
`Idempotency-Key` header when retry safety matters; a key can also be included
as `idempotencyKey` in the body.

The JSON body has this shape:

`{ "title": "Bundle title", "description": "Optional summary", "visibility": "unlisted", "root": "index.md", "files": [{ "path": "index.md", "content": "Markdown source" }] }`

Titles are limited to 200 characters, descriptions to 2,000 characters, and
paths must be safe relative `.md` paths. Visibility is `public`, `unlisted`,
or `password`; password visibility requires a `password` of 8-256 characters,
and other visibility modes reject that field. A successful create returns HTTP
201 with the share `id`, `slug`, and status. The viewer URL is `/s/:slug`.

`POST /api/v1/shares/:id/revisions` publishes a new immutable revision from the
same body and requires `workspace:write` plus an `Idempotency-Key`.
`GET /api/v1/shares/:id/revisions` lists revision history with
`workspace:read`. `POST /api/v1/shares/:id/revisions/:revision/rollback`
creates a new current revision from selected content and requires
`workspace:write` plus an `Idempotency-Key`.

## OKF v0.2 basics

OKFShare consumes the [OKF v0.2 specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
Bundles contain Markdown files with safe relative paths, a root file, and metadata.
Non-reserved concept files need a non-empty free-form `type`; `index.md` and
`log.md` follow their v0.2 structures. Markdown links may use absolute
bundle-relative paths. Files are limited to 100 KB each and a bundle to 1 MB.

## CLI

Install or run the current CLI with `npx okfshare@latest`. Commands are:

`setup`, `login`, `logout`, `whoami`, `doctor`, `validate`,
`publish`, `list`, `open`, `update`, `rollback`, `diff`, `pull`,
`search`, `context`, `bind`, `unbind`, `status`, `skills`, and
`version`.

Examples:

`npx okfshare@latest setup`

`npx okfshare@latest doctor --json`

`npx okfshare@latest validate ./knowledge`

`npx okfshare@latest publish ./knowledge --yes`

`npx okfshare@latest update SHARE_ID ./knowledge --yes`

`npx okfshare@latest rollback SHARE_ID REVISION --yes`

`npx okfshare@latest list`

`npx okfshare@latest open SHARE_ID`

`npx okfshare@latest pull SHARE_ID ./knowledge --revision current --yes`

`npx okfshare@latest search SHARE_ID "deployment safety" --revision 3 --limit 10`

`npx okfshare@latest context SHARE_ID "deployment safety" --max-tokens 1200`

`npx okfshare@latest diff SHARE_ID FROM TO`

`npx okfshare@latest bind SHARE_ID ./knowledge --revision 3`

`npx okfshare@latest unbind ./knowledge`

`npx okfshare@latest status ./knowledge`

`npx okfshare@latest version`

`npx okfshare@latest skills install okfshare --yes`

Use `npx okfshare@latest setup` for onboarding.

### Authentication onboarding

Device-code pairing needs a human to open the verification URL and approve the
device in a browser. Agents must not attempt to complete that approval. A
pre-provisioned API key or CLI credential may instead be supplied via
`OKFSHARE_TOKEN`, kept outside chat, argv, and project files. Agents may check
only whether `OKFSHARE_TOKEN` exists, never read or print its value. Run
`npx okfshare@latest whoami` and `npx okfshare@latest doctor` to verify access.

Use `workspace:read` for retrieval, search, and context; use
`workspace:write` for publishing, updating, rollback, and other mutations.

## Retrieval API

Retrieval uses these authenticated GET routes:

- `/api/v1/shares/:id/bundle` returns source files and the resolved immutable
  revision metadata.
- `/api/v1/shares/:id/search?q=QUERY&limit=LIMIT` returns bounded deterministic
  normalized all-term matches and snippets; `limit` is 1–100.
- `/api/v1/shares/:id/context?q=QUERY&budget=BUDGET` returns selected chunks and
   citations; `budget` is 500–16,000 and the estimate is `chars/4`.
- `/api/v1/shares/:id/revisions/:from/diff/:to` returns bounded machine-readable
  added, removed, and changed files, metadata changes, ancestry, provenance, and
  immutable content digests.
- `/api/v1/workspace/search?q=QUERY&limit=LIMIT&cursor=CURSOR` searches only the
  authenticated workspace with deterministic ranking and cursor pagination.

The CLI syntax for every retrieval command accepts `--revision current` or a
positive integer such as `--revision 3`. Requests require a workspace session
or a Bearer API key or CLI credential with the `workspace:read` scope.
Successful retrieval responses identify the resolved revision; retrieval
responses use `Cache-Control: no-store`. Missing or invalid authentication is
rejected rather than falling back to public viewing.

## Visibility, revisions, and limits

Viewer pages at `/s/:slug` can be public, unlisted, or password-protected. Public
pages are discoverable; unlisted pages need their link; password pages require the
share password and then use a signed access cookie. This viewer visibility is
separate from source retrieval: retrieval is always workspace-authenticated.

Updates create immutable revisions. Rollback selects an existing revision and
creates a new current revision whose manifest points to the selected content;
earlier revisions remain immutable. Free workspaces start with 25 shares,
100 MB of stored share data, and 20 API keys; paid plans raise these limits.
Each bundle has at most 25 files, 100 KB per file, and 1 MB total.

The CLI `pull` validates returned paths and limits before staging the complete
destination. Its destination must not already exist, and it never overwrites
existing files, directories, or symlinks. A failed final placement may leave a
partial destination so existing data is not removed.

## Safety and privacy

Do not publish passwords, API keys, tokens, credentials, or other sensitive data.
The service sanitizes Markdown before rendering, treats bundle references as inert,
uses scoped authentication for publishing and retrieval, and does not include
secrets or workspace data in these documents. CLI credentials are stored using an
OS credential helper when available or a restricted local file; `OKFSHARE_TOKEN`
can override stored credentials.

## Links

- Site: https://okfshare.app/
- Discovery: https://okfshare.app/llms.txt
- Full document: https://okfshare.app/llms-full.txt
- OKF v0.2 specification: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
- CLI package: https://www.npmjs.com/package/okfshare
- Setup: `npx okfshare@latest setup`
- GitHub repository: https://github.com/MegaPanchamZ/okfshare