Commons publishing protocol v1

The protocol defines how a file becomes a discoverable company document. It does not depend on a particular hosting provider or search engine. The repository is the source of truth; the website is a generated artifact.

Document bundle

documents/
  a-stable-slug/
    document.json
    note.md
    images/diagram.png

Each immediate directory under documents/ is one document. It contains a metadata manifest, one UTF-8 .md or .html entrypoint, and optional assets. The CLI imports into this layout. Authors can also create compliant bundles without using the CLI.

{
  "schema_version": 1,
  "slug": "a-stable-slug",
  "title": "A useful document",
  "summary": "Enough context to decide whether to open it.",
  "owner": "Platform",
  "tags": ["decisions"],
  "created": "2026-10-22",
  "updated": "2026-10-22",
  "status": "published",
  "entrypoint": "note.md"
}

Required rules

• schema_version is the integer 1.
• The directory name equals slug. Slugs contain lowercase ASCII letters, digits, and single separating hyphens. Keep slugs stable after publication.
• title and owner are non-empty strings of at most 200 characters. summary is non-empty text of at most 1,000 characters.
• tags is a list of up to 20 non-empty strings, each at most 40 characters.
• created and updated are ISO calendar dates: YYYY-MM-DD.
• status is published or draft.
• entrypoint names an existing .md or .html file inside the bundle. The root index.html filename is reserved for the generated reader; the importer renames an incoming index.html to source.html.
• Bundle paths remain inside the bundle. Symlinks and hidden files are rejected. Each source or attachment must be no larger than 25 MiB.
• Metadata is data. Builds never execute imported scripts or fetch remote resources to understand a document.

Protocol v1 uses exactly the manifest fields above and rejects unknown fields so misspellings do not silently change publication behavior.

Published addresses and machine interfaces

The configured site URL is https://commons.vimaksh.in. Reader pages and the catalog expose stable URLs. Renaming the GitHub repository should not change those public addresses. A withdrawn document is absent from the generated site; an unknown path returns 404.

Rendering and indexing

Markdown uses CommonMark with tables and strikethrough. Raw HTML inside Markdown is escaped. Use a real .html document when you need a custom interactive layout. Headings receive stable generated IDs for fragment links.

HTML source bytes are preserved and displayed in a sandboxed iframe. The original remains available for download. Sandboxing is browser isolation for the embedded document, not an assertion that arbitrary HTML is safe in every context. Only company-authorized publishers should have repository write access.

The search index includes title, summary, owner, tags, and readable body text. It excludes script, style, template, and noscript bodies, and includes the text of inactive HTML tabs. Drafts are excluded from all public outputs. Search requires all query words as word prefixes and ranks title matches above tags, summary, and body matches. Format and topic filters are applied before matching.

The initial implementation uses a static JSON index. It has no search server, third-party search API, or analytics. This is intended for a small shared library. Pagefind can replace that implementation when index size and query latency justify it; the document bundle and public URL contract can stay the same.

Publishing states

1. commons add imports a file locally.
2. commons preview builds and serves it on 127.0.0.1.
3. commons publish validates, commits document changes, and pushes.
4. The hosting provider builds the committed state and publishes it.

A pushed commit is distinct from a completed deployment. Failed builds must not replace the last valid site. Each author works in a separate Git checkout; Git handles concurrent edits and conflicts. The CLI does not hide or resolve those conflicts automatically.

Compatibility

The CLI fails on an unsupported protocol version. Future additive or breaking changes should have an explicit migration and compatibility policy. Preserve historical experiment evidence separately from edits to a published narrative.