๐Ÿ–‹๏ธ
optional/skwrit ยท v1

SKWRIT

Draft to writ: verified paperwork, published into your own fleet.

skwrit turns a taught process into verified paperwork: drafting with quality gates, an independent review step, a release step, and publishing straight into your fleet's own Nextcloud-based collaboration hub, with a re-download check that confirms the published copy actually matches what was sent.

What skwrit is

skwrit is the worker behind the "skwrit matter engine," deployed as an optional role (optional/skwrit) inside SKStacks, the Ansible plus Docker Swarm framework that stands up the rest of the SKWorld fleet. It is new this release cycle, opt-in, and changes nothing for an instance that never deploys it.

One worker, one job

A single worker service, one replica, port 8080, deployed with a stop-first update strategy so a bad update rolls back automatically rather than leaving a half-updated pipeline running.

/health tells the truth

The health endpoint reports back the status of the corpus, the quality gate, and the render assets, not just "process is up."

Pinned, not built here

The engine's code and its "packs" (the taught-process definitions) live in a separate, private repository and ship as a container image built per site. This role deploys that image, it does not build the engine, and it refuses to run without a full @sha256: digest pin.

Re-download check

After a document is published into skhub, skwrit re-downloads its own publish to confirm the copy that landed actually matches what was sent, not just that the upload call returned success.

Why this is the right way to build it

The architecture is not ornamental. Every piece exists to narrow a specific blast radius.

  1. Secrets by reference, never by value. Every credential skwrit needs (a Nextcloud account password, its own worker bearer token, a vector-store access key) is an external Docker Swarm secret, referenced by name only. The Ansible play that deploys it refuses to even start if a referenced secret, or its required network, is missing. The deployment automation that configures the worker is never the thing holding the credential.
  2. Independent review by design. The reviewer model and endpoint are configured separately from the composer model and endpoint (REVIEW_MODEL / REVIEW_URL versus MODEL / MODEL_URL). Drafting and review are two distinct configured steps in the pipeline, not one model checking its own homework by default.
  3. Calls your own infrastructure, not a cloud SaaS. skwrit publishes into your fleet's own self-hosted Nextcloud (skhub), can use your fleet's own vector store and embeddings endpoints, and is itself called by your fleet's own workflow engine over a private, internal Docker Swarm overlay network, never over the public internet. The worker is reached at a private Swarm DNS name, not a public URL.
  4. Reproducible, vault-driven, and digest-pinned. It deploys through the same Ansible pattern as every other service in the fleet, per environment (dev, staging, prod), with the same naming, resource-limit, logging, and healthcheck conventions as its sibling roles, rather than a bespoke one-off deployment.
  5. State lives outside the container. Its database and private render assets sit on an external, named volume, so redeploying the worker does not touch its data.

How it fits the workflow

skwrit sits between three other SKWorld pieces: your fleet's workflow engine (skflow, built on Windmill, which calls the worker directly over the private overlay to drive a draft, review, publish pipeline as a taught process), your fleet's own Nextcloud-based collaboration hub (skhub, where the finished, reviewed document is actually published, readable afterward through the same web, desktop-sync, and mobile clients everyone already uses), and your fleet's own model-serving layer (the composer and reviewer endpoints point at your operator's own inference gateway, skgateway, rather than a hardcoded cloud API).

draft -> quality gate -> independent review -> release -> publish into skhub -> re-download check (does it match?)

The name plays on the idea of a writ: a formal, binding, executed document. skwrit is a process that goes from draft to a reviewed, released, published piece of paperwork, not a chatbot that free-writes.

What's real today, what's planned

Real today

The deploy role, its render tests (a real Ansible test suite covering defaults, every configuration knob, naming, and every refusal path), the secrets-by-reference model, the independent reviewer configuration split, the /health endpoint, and an optional Nextcloud MCP service, also digest-pinned, letting AI tooling interact with the Nextcloud side of the pipeline through a standard tool-calling interface.

Planned, not yet shipped

Unlike some of its sibling roles (skhub, for example), skwrit has not yet been folded into the framework's own pre-release lab-gate harness (skstack06) that exercises other roles end to end against a disposable live stack before each release. That is a natural next step for this role, but it is not yet true today.

If you see a claim elsewhere that skwrit is already lab-gated, that is wrong for this release. The lab-gate claim belongs to skhub, not skwrit, today.

Read the source

skwrit's facts live in the actual role, not in a pitch. Start with the README that this page is grounded in, then the framework it deploys into.