From 4a9f23c7597126d561c7960f42b4803e9e483850 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Padez?= Date: Sat, 15 Aug 2026 01:07:48 +0000 Subject: [PATCH] the design doc moves into the plugin it produced MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/offscale-plugin.md becomes plugins/offscale/PLUGIN.md. most of it is about the plugin system generally rather than about offscale, which is exactly why it belongs with the worked example — the reasoning is most useful beside the code it produced, and the platform's docs should not carry the history of something it no longer knows exists. every reference updated. Co-Authored-By: Claude Opus 5 --- docs/offscale-plugin.md => plugins/offscale/PLUGIN.md | 9 +++++++-- plugins/offscale/manifest.ts | 2 +- src/apps/officer-web/App.tsx | 2 +- src/servers/plugins/manifest.ts | 5 +++-- 4 files changed, 12 insertions(+), 6 deletions(-) rename docs/offscale-plugin.md => plugins/offscale/PLUGIN.md (98%) diff --git a/docs/offscale-plugin.md b/plugins/offscale/PLUGIN.md similarity index 98% rename from docs/offscale-plugin.md rename to plugins/offscale/PLUGIN.md index a21ee42b..c4994201 100644 --- a/docs/offscale-plugin.md +++ b/plugins/offscale/PLUGIN.md @@ -1,7 +1,12 @@ # Offscale — the first real plugin -**Status: LIVE DOCUMENT, opened 2026-08-14.** Decisions and findings from the session that started the -plugin system. Correct it in place; it is meant to be edited, not archived. +**Status: LIVE DOCUMENT, opened 2026-08-14, offscale extracted 2026-08-15.** Decisions and findings from +the session that built the plugin system. Correct it in place; it is meant to be edited, not archived. + +It lives HERE, in the plugin, rather than in the platform's `docs/`. Most of it is about the plugin +system generally rather than about offscale, and that is deliberate: this is the worked example, and the +reasoning is most useful next to the code it produced. The platform's own docs should not carry the +history of something it no longer knows exists. Offscale is Headscale extracted into a plugin. It is the pilot: chosen because it is a genuine vertical slice (schema + backend router + sidecar + frontend screen + capabilities) without being pathological. diff --git a/plugins/offscale/manifest.ts b/plugins/offscale/manifest.ts index a1c34360..2a01d9ad 100644 --- a/plugins/offscale/manifest.ts +++ b/plugins/offscale/manifest.ts @@ -27,7 +27,7 @@ export const manifest: PluginManifest = { // `[open]` What a member's grant MEANS here is this plugin's own job and is not finished. The queries // still scope by the caller (`listHeadscaleServers(userId)`), so a granted member would see their own // empty server list rather than the owner's, and could register a Headscale of their own. The model in - // docs/offscale-plugin.md is one shared resource: read sees what the owner sees, write can change it. + // ./PLUGIN.md is one shared resource: read sees what the owner sees, write can change it. // That is a change inside these queries, not a flag on the manifest. // // Worth knowing while it is unfinished: the stored credential is a Headscale ADMIN api key that can diff --git a/src/apps/officer-web/App.tsx b/src/apps/officer-web/App.tsx index d870fefe..ebf93d04 100644 --- a/src/apps/officer-web/App.tsx +++ b/src/apps/officer-web/App.tsx @@ -7,7 +7,7 @@ import { useServerEnvironment } from 'state/useServerEnvironment'; import { useInitialData } from '@/state/useInitialData'; // `installedPlugins`, not `plugins`: App.tsx already destructures a `plugins` from useServerSettings(), // which is the DEAD plugin system — /server-settings/plugins scans src/workspaces/plugins/, a directory -// that does not exist, so it is always []. Different thing entirely; see docs/offscale-plugin.md. +// that does not exist, so it is always []. Different thing entirely; see plugins/offscale/PLUGIN.md. import { plugins as installedPlugins } from './Plugins.gen'; export function App() { diff --git a/src/servers/plugins/manifest.ts b/src/servers/plugins/manifest.ts index b624203d..39f10b57 100644 --- a/src/servers/plugins/manifest.ts +++ b/src/servers/plugins/manifest.ts @@ -10,7 +10,8 @@ // the tile is `{ label, icon, color, to: mountPrefix() }` and the title is `label`, all of which are // already below. Writing them twice could only ever drift. // -// See docs/offscale-plugin.md for the reasoning behind each decision recorded here. +// The reasoning behind every decision here is recorded in plugins/offscale/PLUGIN.md — the worked +// example, kept next to the plugin it produced rather than in the platform's docs. /** * A permission the plugin adds to the platform's permission system. @@ -34,7 +35,7 @@ export type PluginPermission = { // // Finer visibility — whose rows a member sees, what a read means for this plugin's data — is the // PLUGIN's business and lives in its own queries. The platform's answer is uniform: read, write, or - // nothing. See docs/offscale-plugin.md. + // nothing. See plugins/offscale/PLUGIN.md. /** * Requests that look like writes and are not — `POST /ssh-test` probes, `POST /policy/assist` proposes * a document and never saves one. Without declaring them, a read-level account meets what reads as a