From daecc6d45605c6cc73019cde45055bc7418f982a Mon Sep 17 00:00:00 2001 From: rcourtman Date: Mon, 3 Aug 2026 09:54:28 +0100 Subject: [PATCH] Sync shipped docs with the AI transparency link 17f113708 added the AI-Assisted Development entry to docs/README.md but left the shipped copy under frontend-modern/public/docs untouched, so the docs-sync test failed and Build and Test stayed red once the lint error in front of it was cleared. Copy the README across and ship AI_TRANSPARENCY.md too, otherwise the new entry resolves to a missing /docs/AI_TRANSPARENCY.md in the in-app viewer. Add the pair to the sync test so the two cannot drift again. Contract-Neutral: shipped documentation sync, no contract delta --- .../public/docs/AI_TRANSPARENCY.md | 84 +++++++++++++++++++ frontend-modern/public/docs/README.md | 1 + .../src/utils/__tests__/docsLinks.test.ts | 4 + 3 files changed, 89 insertions(+) create mode 100644 frontend-modern/public/docs/AI_TRANSPARENCY.md diff --git a/frontend-modern/public/docs/AI_TRANSPARENCY.md b/frontend-modern/public/docs/AI_TRANSPARENCY.md new file mode 100644 index 000000000..d1fdd7f52 --- /dev/null +++ b/frontend-modern/public/docs/AI_TRANSPARENCY.md @@ -0,0 +1,84 @@ +# AI-Assisted Development + +Pulse is built with AI tools, extensively and deliberately. This page exists so +there is no ambiguity about that, and so nobody has to guess. + +## The short version + +I am the sole maintainer of Pulse. I use AI assistance throughout the project. +Code, tests, documentation, release notes, and issue replies may all be +produced with AI tools in the loop. Everything ships under my direction, my +review, and my responsibility. If something is wrong, it is my bug, regardless +of what typed the first draft. + +## Why + +Pulse monitors Proxmox, PBS, Docker, Kubernetes, TrueNAS, and vSphere. Around +that sits a web UI, a mobile app, host agents, installers, release tooling, +security processes, and a support queue. That surface area is well beyond what +one person can sustain by hand at any reasonable quality bar. + +AI assistance is the reason a solo project can cover that breadth, ship +frequent releases, and usually turn a reproducible bug report into a fix in +days rather than months. Refusing these tools would not make Pulse better. It +would make it slower and buggier. I consider working this way a professional +obligation, not a shortcut. + +## Where it is used + +Declaring the general position is easy. Declaring where it applies is more +useful, so here is the breakdown. + +- **Code and tests.** Much of both is written with AI coding tools, working + from my direction and landing through the same review, test, and audit + gates as anything else. +- **Documentation and release notes.** Drafted with AI assistance and checked + against the actual code and behaviour before publishing. +- **Issue triage and support.** AI helps investigate reports, reproduce bugs, + and draft replies. When a response comes from an automated triage run + rather than from me at the keyboard, it posts under the dedicated + pulse-triage bot identity and carries a footer saying so, with a link back + to this page. I would rather you know you are reading automation than + wonder whether you are. + +## What stays human + +The tools write a lot of the code. They do not decide what Pulse is. Product +direction, architecture, what gets built and what gets cut, review of what +ships, and every release decision are mine. When you report a bug, the +investigation may be automated, but what the fix should be and whether it is +good enough to ship is my call, and I own the outcome of every thread either +way. + +## What it does not change + +Pulse is judged the same way all software should be judged, by what it does. +The test suites, the audit gates that run before anything lands, the release +candidate process, and the issue tracker history are all public. If you find a +bug, report it with steps to reproduce and it will get fixed. "This looks +AI-written" is not a bug report, and style-sniffing a diff or an issue reply +tells you nothing about whether the code is correct. + +## From here on + +This document sets the standard from the day it landed, not a claim about the +past. I used AI for a long time before writing any of this down, and some of +that use was not declared, including automated issue replies that carried +nothing to say they were automated. I am not going to rewrite history or +pretend otherwise. What I can do is state the rules now and hold to them going +forward. + +## If you object on principle + +That is your call, and I am not going to argue anyone out of it. But I am also +not going to pretend, hedge, or apologise. Nearly every actively developed +software project you rely on today is built with some level of AI assistance, +whether its maintainers say so or not. I would rather say so. + +Judge Pulse on what it does on your infrastructure and on the track record in +the [issue tracker](https://github.com/rcourtman/Pulse/issues). Those are the +things that matter, and they are the things I stand behind. + +For what Pulse itself does with AI as a product (Pulse Patrol, Assistant, and +MCP, all optional and off by default until you configure a provider), see +[AI.md](AI.md). diff --git a/frontend-modern/public/docs/README.md b/frontend-modern/public/docs/README.md index 7e95c2228..a9760983d 100644 --- a/frontend-modern/public/docs/README.md +++ b/frontend-modern/public/docs/README.md @@ -116,6 +116,7 @@ Pulse is available in three self-hosted tiers plus hosted Cloud: - **[API Reference](API.md)** – Complete REST API documentation. - **[Architecture](../ARCHITECTURE.md)** – System design and component interaction. - **[Contributing](../CONTRIBUTING.md)** – How to contribute to Pulse. +- **[AI-Assisted Development](AI_TRANSPARENCY.md)** – How AI tools are used to build and maintain Pulse, and where their output is labelled. ## 📁 Previous Versions diff --git a/frontend-modern/src/utils/__tests__/docsLinks.test.ts b/frontend-modern/src/utils/__tests__/docsLinks.test.ts index 8acce76dd..68ad24e41 100644 --- a/frontend-modern/src/utils/__tests__/docsLinks.test.ts +++ b/frontend-modern/src/utils/__tests__/docsLinks.test.ts @@ -81,6 +81,10 @@ describe('docsLinks', () => { target: 'MIGRATION_UNIFIED_NAV.md', }, { source: path.join(repoRoot, 'docs', 'PRIVACY.md'), target: 'PRIVACY.md' }, + { + source: path.join(repoRoot, 'docs', 'AI_TRANSPARENCY.md'), + target: 'AI_TRANSPARENCY.md', + }, { source: path.join(repoRoot, 'docs', 'CONFIGURATION.md'), target: 'CONFIGURATION.md' }, { source: path.join(repoRoot, 'docs', 'PROXY_AUTH.md'), target: 'PROXY_AUTH.md' }, { source: path.join(repoRoot, 'docs', 'i18n', 'README.md'), target: 'i18n/README.md' },