From 54c30273d603924150f5be252a025f41c07585d1 Mon Sep 17 00:00:00 2001 From: Matt Hill <9935159+MattDHill@users.noreply.github.com> Date: Sun, 16 Aug 2026 21:38:59 -0600 Subject: [PATCH 1/2] docs(sdk): drop the fleet-provenance clause from the description advice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "Two more characters' worth of advice, both from descriptions already in the registries" — the provenance half is a claim about what the fleet's short descriptions look like right now, with nothing keeping it true. It is already only partly accurate: 4 of the 107 packages with an en_US short open with the service name, which is the pattern the first bullet tells you to avoid. The two bullets it introduces both have live producers and stay exactly as written. Split out from the rest of the packaging-guide cruft audit because this paragraph exists only on master — the published guide does not carry it, so it cannot be fixed on live-docs. Co-Authored-By: Claude Opus 5 (1M context) --- projects/start-sdk/docs/src/manifest.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/projects/start-sdk/docs/src/manifest.md b/projects/start-sdk/docs/src/manifest.md index 8b7b3c6ed..fe1f8f8d1 100644 --- a/projects/start-sdk/docs/src/manifest.md +++ b/projects/start-sdk/docs/src/manifest.md @@ -46,8 +46,7 @@ routinely run 20-30% longer than the same English sentence — not as permission to run long. Write the English well inside 80 and every locale still fits the tile. -Two more characters' worth of advice, both from descriptions already in the -registries: +Two more characters' worth of advice: - **Don't open with the service's name.** The tile renders the title in bold on the line directly above, so "Foo is a self-hosted bar" spends its first words From 0edf9ceab54dfe8daba0e43cd02ef0c359eccc9b Mon Sep 17 00:00:00 2001 From: Matt Hill <9935159+MattDHill@users.noreply.github.com> Date: Sun, 16 Aug 2026 21:54:26 -0600 Subject: [PATCH 2/2] docs: delete scope-doc text with no live producer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Audited all 65 AGENTS.md / ARCHITECTURE.md / CONTRIBUTING.md files across every scope against one test: a sentence citing what not to do, what not to include, or a mistake once made must name a live producer — a scaffold that emits it, a neighbour someone would copy, a tool that does it unless you intervene, or an obvious-but-wrong fix someone would reach for. No producer, delete. Facts that are simply wrong: - start-registry's CONTRIBUTING said its Cargo version "tracks the OS release line — don't bump it independently", while its own AGENTS.md one directory over says the opposite. The crate is 1.0.2 and StartOS is 0.4.0.2, so the CONTRIBUTING rule is the retired one. Its "(currently 1.0.0)" had drifted too. - rpc-toolkit's CONTRIBUTING described a `rustfmt.toml` the crate does not ship; only the repo root has one. - start-sdk's build table documented `make dist`, which is not a target in that Makefile (start-core's `make dist`, referenced further down the same file, is real and stays). - The root ARCHITECTURE tree put `apt/` under projects/start-os/; it is at the repo root. - shared-libs' CONTRIBUTING said ts-modules' contents are Angular libraries; it also holds the non-Angular start-core. - start-registry's ARCHITECTURE counted "all five product binaries"; the root AGENTS.md counts six. - start-sdk's ARCHITECTURE listed AGENTS.md twice in Further reading. Migration narration whose migration is over: Four separate stale-path notes mapped the pre-monorepo root layout (`core/`, `web/`, `sdk/`, `patch-db/`, `container-runtime/`). The root AGENTS.md keeps one — `core/src/` is still referenced live in projects/start-os/DEV_TODO.md, so the mapping is still reachable — and the copies in start-cli, container-runtime and shared-libs go, along with "Internally unchanged from the old `core/` crate", the start-fs migration note, the retired start-os submodule's workspace Cargo.toml, and the `base/lib/...` import shape. The retired `next/patch` | `next/minor` | `next/major` prohibition goes from AGENTS.md; the mapping line in the root CONTRIBUTING.md stays, which is the one line the still-reachable-artifact rule allows. Counts and in-progress markers: `~430 tests` (twice), `11 modules` (twice), `~28 utility modules`, `~117-line`, `~2200 lines`, `all five product binaries`, `currently 1.0.0`, `3 small build-infra patches`, `(currently by start-core)`, `(currently just bitcoin-guides)`, `(currently the Angular libs shared and marketplace)` (twice), the SDK/OS version pair, `being replaced`, `being phased out`, the per-scope CONTRIBUTING migration tally (three copies), the patch-db repo "is being retired" (the repo is still live and was pushed to after the claim was written), and two notes recording which warnings a crate happened to emit. Also drops a commented-out list of ten aspirational locales, a prohibition against putting files directly in shared-libs/ (nothing but doc files ever has, across the directory's whole history), and a prohibition against nesting tab groups more than one level, which restates the positive rule in the sentence before it. Includes the fleet-provenance clause in the packaging guide's manifest.md, which can only be fixed here — the rest of that audit is on live-docs. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 10 +++++----- ARCHITECTURE.md | 2 +- CONTRIBUTING.md | 4 ++-- projects/start-cli/AGENTS.md | 6 +----- projects/start-docs/ARCHITECTURE.md | 4 ++-- projects/start-docs/CONTRIBUTING.md | 2 +- projects/start-os/ARCHITECTURE.md | 8 +++----- projects/start-os/container-runtime/AGENTS.md | 6 +----- projects/start-registry/AGENTS.md | 2 +- projects/start-registry/ARCHITECTURE.md | 4 +--- projects/start-registry/CONTRIBUTING.md | 1 - projects/start-sdk/AGENTS.md | 3 +-- projects/start-sdk/ARCHITECTURE.md | 7 +++---- projects/start-wrt/CONTRIBUTING.md | 3 +-- projects/start-wrt/backend/AGENTS.md | 5 ++--- projects/start-wrt/backend/ARCHITECTURE.md | 4 ++-- projects/start-wrt/backend/CONTRIBUTING.md | 2 +- projects/start-wrt/web/CONTRIBUTING.md | 2 +- shared-libs/AGENTS.md | 6 ++---- shared-libs/CONTRIBUTING.md | 2 +- shared-libs/crates/exver/AGENTS.md | 2 +- shared-libs/crates/jsonpath/AGENTS.md | 5 ++--- shared-libs/crates/jsonpath/CONTRIBUTING.md | 5 ++--- shared-libs/crates/pi-beep/AGENTS.md | 4 ++-- shared-libs/crates/pi-beep/CONTRIBUTING.md | 3 +-- shared-libs/crates/rpc-toolkit/CONTRIBUTING.md | 8 ++------ shared-libs/crates/start-core/AGENTS.md | 3 +-- shared-libs/crates/yasi/AGENTS.md | 4 ++-- shared-libs/ts-modules/CONTRIBUTING.md | 10 ---------- 29 files changed, 45 insertions(+), 82 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c2b44d34b..ebef30968 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,11 +4,11 @@ Agent/developer operating rules for the **start-technologies monorepo root**. Th See [ARCHITECTURE.md](ARCHITECTURE.md) for the layout and [CONTRIBUTING.md](CONTRIBUTING.md) for the build/test/format workflow. -**Keep these docs current.** Every scope carries `AGENTS.md` / `ARCHITECTURE.md` / `README.md`, most still with a `CONTRIBUTING.md` beside them (and `CLAUDE.md`, a one-line `@AGENTS.md` import). When a change alters structure, conventions, the build/test/release flow, or product context, update the matching doc(s) in the **same change** — never defer. These docs are **hierarchical**: each scope's docs cover only what is specific to it and must not repeat anything already stated at a higher scope (e.g. commit/PR conventions live only in this root `CONTRIBUTING.md`). +**Keep these docs current.** Every scope carries `AGENTS.md` / `ARCHITECTURE.md` / `README.md` (and `CLAUDE.md`, a one-line `@AGENTS.md` import). When a change alters structure, conventions, the build/test/release flow, or product context, update the matching doc(s) in the **same change** — never defer. These docs are **hierarchical**: each scope's docs cover only what is specific to it and must not repeat anything already stated at a higher scope (e.g. commit/PR conventions live only in this root `CONTRIBUTING.md`). **Anything an agent must follow belongs _in_ `AGENTS.md`, not behind a link from it.** The `AGENTS.md` standard is plain Markdown with **no import syntax** — unlike `CLAUDE.md`, whose `@file` imports expand into context at launch. So a pointer in `AGENTS.md` ("see X for the release process") is just a suggestion that the agent spend a tool call, and agents routinely don't: that is exactly how start-sdk 2.0.4 and 2.0.5 shipped untagged. Inline the rule; link only to _reference_ material an agent can safely skip (`ARCHITECTURE.md`, a product book). `CLAUDE.md` stays a one-line `@AGENTS.md` import — Claude Code does not read `AGENTS.md` natively. -**So `CONTRIBUTING.md` is being folded into `AGENTS.md` — in every scope _but_ the root.** A sub-scope `CONTRIBUTING.md` earns nothing (GitHub gives it no special treatment) and costs an agent a hop, so its contents belong in that scope's `AGENTS.md`. `projects/start-sdk/` is migrated and has none; every other scope still has the split. When you next do substantial work in a scope that hasn't migrated, fold its `CONTRIBUTING.md` into its `AGENTS.md`, delete it, and repoint every inbound link in the same change — don't leave dangling cross-references, and don't migrate scopes you aren't otherwise touching. **The root [`CONTRIBUTING.md`](CONTRIBUTING.md) stays**: GitHub surfaces it (the contributing prompt on new issues/PRs, the community profile), so it remains the human-facing front door — the social layer, and a pointer _to_ `AGENTS.md` for the mechanics. That pointer runs one way; a human will follow a link, an agent won't. +**So `CONTRIBUTING.md` is being folded into `AGENTS.md` — in every scope _but_ the root.** A sub-scope `CONTRIBUTING.md` earns nothing (GitHub gives it no special treatment) and costs an agent a hop, so its contents belong in that scope's `AGENTS.md`. When you next do substantial work in a scope that hasn't migrated, fold its `CONTRIBUTING.md` into its `AGENTS.md`, delete it, and repoint every inbound link in the same change — don't leave dangling cross-references, and don't migrate scopes you aren't otherwise touching. **The root [`CONTRIBUTING.md`](CONTRIBUTING.md) stays**: GitHub surfaces it (the contributing prompt on new issues/PRs, the community profile), so it remains the human-facing front door — the social layer, and a pointer _to_ `AGENTS.md` for the mechanics. That pointer runs one way; a human will follow a link, an agent won't. **A product's user docs and changelog ship with the code.** Any change that alters user-visible behavior **must** update that product's user-facing documentation book (its `docs/` directory — e.g. `projects/start-os/docs/`, `projects/start-tunnel/docs/`, `projects/start-sdk/docs/`) in the **same change**, and **must** add a `CHANGELOG.md` entry for that product (a version bump always pairs with its changelog). Don't land code and defer its docs or changelog to a follow-up. The conventions for authoring **any** of those books — mdBook versions, admonitions, tabs, `SUMMARY.md`, the shared `theme/` — live in [`projects/start-docs/AGENTS.md`](projects/start-docs/AGENTS.md) and its `CONTRIBUTING.md`. That project is a sibling, not an ancestor, so nothing loads it for you: read it before editing book pages anywhere in the repo. @@ -30,7 +30,7 @@ Each product lives under `projects/` as a thin wrapper; the bulk of the code liv - `projects/start-sdk/` — `@start9labs/start-sdk` (source in `lib/`; imports the shared `@start9labs/start-core` lib and bundles it into its published `dist/`) + `Makefile`/`s9pk.mk` + `docs/` (packaging mdbook). - `projects/brochure-marketplace/` — public marketplace/landing Angular app (deploys to marketplace.start9.com). - `projects/start-docs/` — the documentation website (build infra + landing + Bitcoin guides; each product's own book lives in its `docs/`). -- `shared-libs/crates/start-core/` — the **entire** Rust backend lib (package `start-core`, lib name `start_core`). All six bins depend on it. Internally unchanged from the old `core/` crate. +- `shared-libs/crates/start-core/` — the **entire** Rust backend lib (package `start-core`, lib name `start_core`). All six bins depend on it. - `shared-libs/ts-modules/` — shared **TypeScript** modules (the common thread is just that they are TS — not Angular-specific). These are the Angular libs `shared/` (`@start9labs/shared`) and `marketplace/` (`@start9labs/marketplace`), plus the non-Angular `start-core/` (`@start9labs/start-core`: SDK core types/ABI/effects/OS bindings, the TS projection of the `start-core` crate, consumed by web and bundled into the SDK; versionless, not published separately). The Angular workspace is rooted at the repo root (`angular.json`/`package.json`). Product apps reference the libs by package name. - Top level also holds the shared build infra (`build/`, `Makefile`), `apt/`, the shared `debian/build.sh`, `scripts/` (maintainer release tooling — `manage-release.sh ` drives a product through pre-check/tag/release/sign/publish; `deploy-migration-payload.sh` publishes a 0.3.5.1 → 0.4.0 migration OTA payload to a legacy registry), `rfcs/` (protocol drafts), and `shared-libs/crates/patch-db/` (first-party crate, consumed by `start-core` and web). @@ -44,7 +44,7 @@ Each product lives under `projects/` as a thin wrapper; the bulk of the code liv ## Branches and channels - **`master` is always shippable, and every push to it publishes.** Only merge work that is finished and tested: a master push indexes StartOS images into the alpha registry, publishes `.deb`s into the `alpha` apt suite, and — once the `STARTWRT_ALPHA_REGISTRY` repo variable is set — StartWRT images into its alpha registry. There is no staging step between merging and publishing. The SDK is the deliberate exception: an npm version can never be republished, so it publishes only on release. -- **Work that can't land piecemeal goes on `integration/`.** Land the pieces there as ordinary PRs, soak the branch as a unit, and delete it on merge. The PR merging it into master is the last gate before it ships, so CI builds the full flashable image matrix on that PR specifically — the bypass lives in `startos-iso.yaml`'s `changes` job and start-wrt's `image` job, both keyed on `head_ref` starting with `integration/` and `base_ref` being `master`. The old `next/patch` | `next/minor` | `next/major` branches are **retired**; don't add a workflow trigger for them. +- **Work that can't land piecemeal goes on `integration/`.** Land the pieces there as ordinary PRs, soak the branch as a unit, and delete it on merge. The PR merging it into master is the last gate before it ships, so CI builds the full flashable image matrix on that PR specifically — the bypass lives in `startos-iso.yaml`'s `changes` job and start-wrt's `image` job, both keyed on `head_ref` starting with `integration/` and `base_ref` being `master`. - **Re-indexing a version into a registry requires removing it first.** `registry os asset add` upserts the platform slot but **rejects** a write whose blake3 differs from the commitment already there (`registry/os/asset/add.rs`, `registry.os.asset.commitment-mismatch`) — so publishing a second build under a version number that already holds one fails, even though `registry os version add` itself is a harmless upsert. Alpha rolls the same version on every master push, so both deploy jobs run `registry os version remove` first. Anything that re-publishes a version in place must do the same. - **Alpha is the source a release is promoted from, so a master push must build release-equivalent artifacts.** `os promote` copies each asset's URL and signed commitment through verbatim (`registry/os/promote.rs`), so the bytes a master push uploads are the bytes production eventually serves — from the same S3 key. Two consequences: `ENVIRONMENT` is empty on master (only PRs and `integration/*` default to `dev`), and alpha images must **not** be given a separate S3 prefix, or promoted production assets would point inside it. It also means an S3 key, once published, is immutable: both deploy jobs refuse to overwrite an object that already exists and fail listing every conflict, since replacing those bytes would leave an already-promoted signature validating against content that no longer matches. Re-running a deploy for a commit that was published before therefore needs a dispatch with `force-overwrite`. @@ -156,4 +156,4 @@ Already enforced or checked elsewhere (listed here for completeness; documented - [`projects/brochure-marketplace/AGENTS.md`](projects/brochure-marketplace/AGENTS.md) — public marketplace site - [`projects/start-docs/AGENTS.md`](projects/start-docs/AGENTS.md) — documentation website; also the authoring conventions for every product book - [`shared-libs/AGENTS.md`](shared-libs/AGENTS.md) — shared libs container: [`crates/start-core`](shared-libs/crates/start-core/AGENTS.md) (Rust backend), [`web`](shared-libs/ts-modules/AGENTS.md) (Angular workspace + UI/setup-wizard/shared libs) -- `shared-libs/crates/patch-db/` — first-party crate (maintained in-tree; the standalone `Start9Labs/patch-db` repo is being retired) +- `shared-libs/crates/patch-db/` — first-party crate (maintained in-tree) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 6d881731e..f3ba290e0 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -19,7 +19,7 @@ start-technologies/ # repo root (monorepo) │ ├── src/bin/{startbox,start-container}.rs │ ├── web/ # Angular UI + setup-wizard │ ├── container-runtime/ # Node LXC service runtime -│ ├── debian/ apt/ assets/ build/ +│ ├── debian/ assets/ build/ │ ├── *.service services.slice │ └── Cargo.toml # → depends on start-core ├── projects/start-cli/ # start-cli bin (src/main.rs) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5910bf6de..703c6bf89 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ This guide is for contributing to the Start9 monorepo (StartOS and the other products that live here). If you are interested in packaging a service for StartOS, visit the [packaging guide](https://docs.start9.com/packaging). If you are interested in promoting, providing technical support, creating tutorials, or helping in other ways, please visit the [Start9 website](https://start9.com/contribute). -This file covers what is **common to the whole monorepo** — the shared toolchain, branch policy, the cross-cutting test/format entry points, and code/commit conventions. **Per-product system dependencies, build targets, deploy steps, and release procedure live in that product's own scope** — its `AGENTS.md` (e.g. [`projects/start-sdk/AGENTS.md`](projects/start-sdk/AGENTS.md)), or its `CONTRIBUTING.md` in scopes not yet migrated (e.g. [`projects/start-os/CONTRIBUTING.md`](projects/start-os/CONTRIBUTING.md) for building the StartOS OS image). See [`AGENTS.md`](AGENTS.md) for that migration and the reasoning behind it. +This file covers what is **common to the whole monorepo** — the shared toolchain, branch policy, the cross-cutting test/format entry points, and code/commit conventions. **Per-product system dependencies, build targets, deploy steps, and release procedure live in that product's own scope** — its `AGENTS.md` (e.g. [`projects/start-sdk/AGENTS.md`](projects/start-sdk/AGENTS.md)), or its `CONTRIBUTING.md` in scopes not yet migrated (e.g. [`projects/start-os/CONTRIBUTING.md`](projects/start-os/CONTRIBUTING.md) for building the StartOS OS image). ## Documentation @@ -13,7 +13,7 @@ The repo root's docs split across four files: - `CONTRIBUTING.md` — this file; how to contribute - `AGENTS.md` — AI-developer/agent operating rules (`CLAUDE.md` is a one-line `@AGENTS.md` import) -**These docs must be kept up to date.** When you change project structure, conventions, build process, or product context, update the relevant file(s) in the same change — do not defer. Each product and shared library keeps its own `README.md`/`ARCHITECTURE.md`/`AGENTS.md` for what is specific to it (most still carry a `CONTRIBUTING.md` too, which is being folded into that scope's `AGENTS.md` — see [`AGENTS.md`](AGENTS.md)) — see `projects/*/`, `shared-libs/crates/start-core/`, `shared-libs/ts-modules/`, and `projects/start-os/container-runtime/`. +**These docs must be kept up to date.** When you change project structure, conventions, build process, or product context, update the relevant file(s) in the same change — do not defer. Each product and shared library keeps its own `README.md`/`ARCHITECTURE.md`/`AGENTS.md` for what is specific to it — see `projects/*/`, `shared-libs/crates/start-core/`, `shared-libs/ts-modules/`, and `projects/start-os/container-runtime/`. ### The user-facing books, and `live-docs` diff --git a/projects/start-cli/AGENTS.md b/projects/start-cli/AGENTS.md index 674b2110e..88167a418 100644 --- a/projects/start-cli/AGENTS.md +++ b/projects/start-cli/AGENTS.md @@ -50,12 +50,8 @@ generator is `cargo test -p start-core export_manpage_start_cli`. falsey → `PREFER_DOCKER` is set (Docker). Truthy (`1/true/y/yes`) → Podman. - **In a StartOS image `start-cli` is a symlink to `startbox`** (see OS `Makefile`), the same `MultiExecutable` multiplexer. The standalone bin here enables only the `start-cli` sub-bin. -- **Stale paths:** older docs referenced `core/`, `web/`, `sdk/`, `patch-db/` at the repo root. - They now live at `shared-libs/crates/start-core`, `shared-libs/ts-modules` + product `web/`, `projects/start-sdk/`, - `shared-libs/crates/patch-db`. Use the new paths. ## Verifying a command -Build the bin, then run it against a StartOS test VM (see root docs for `helix-vm` / -`start-cli` host flow). Remote commands need `-H https://` and an `auth login`; local +Build the bin, then run it against a StartOS test VM. Remote commands need `-H https://` and an `auth login`; local commands (`s9pk`, `init-key`, `pubkey`, `util`) need no server. diff --git a/projects/start-docs/ARCHITECTURE.md b/projects/start-docs/ARCHITECTURE.md index 06b617788..fe54682cb 100644 --- a/projects/start-docs/ARCHITECTURE.md +++ b/projects/start-docs/ARCHITECTURE.md @@ -10,7 +10,7 @@ This is the `projects/start-docs/` project in the `start-os` monorepo. It owns t The site is composed of independent mdBook instances — one per product. Each book has its own `book.toml`, `src/SUMMARY.md`, and content tree. Books build into subdirectories of `docs/` (the build output, gitignored) and are deployed together under a shared domain. -Since this is now part of the `start-os` monorepo, the per-product books live **next to the code they document**, not inside this directory. This `docs/` project owns only the build infra, the shared theme, the landing page, and the Bitcoin Guides book. +The per-product books live **next to the code they document**, not inside this directory. This `docs/` project owns only the build infra, the shared theme, the landing page, and the Bitcoin Guides book. ``` start-os/ (monorepo root) @@ -51,7 +51,7 @@ book_dir() { } ``` -So `packaging` is served from `projects/start-sdk/docs`, and any book not explicitly mapped (currently just `bitcoin-guides`) is expected to live directly under this project (`projects/start-docs/`). To move or add a book, edit `book_dir()` and `versions.conf`. +So `packaging` is served from `projects/start-sdk/docs`, and any book not explicitly mapped is expected to live directly under this project (`projects/start-docs/`). To move or add a book, edit `book_dir()` and `versions.conf`. ## Shared Theme diff --git a/projects/start-docs/CONTRIBUTING.md b/projects/start-docs/CONTRIBUTING.md index 0758cbcfc..82d7bf868 100644 --- a/projects/start-docs/CONTRIBUTING.md +++ b/projects/start-docs/CONTRIBUTING.md @@ -112,7 +112,7 @@ Linux instructions here. - Anything that isn't a general OS picker (backup targets, cloud providers, …) gets its own `global` — don't overload `platform`. - Omit `global` for a one-off, page-local group. -Keep the outer picker flat: the only sanctioned nesting is a single distro/version sub-group (with its own `global`) inside one platform tab. Don't nest `platform` inside `platform`, or nest more than one level deep. +Keep the outer picker flat: the only sanctioned nesting is a single distro/version sub-group (with its own `global`) inside one platform tab. ### Cross-Book Links diff --git a/projects/start-os/ARCHITECTURE.md b/projects/start-os/ARCHITECTURE.md index b000f9a60..b1a8dd7f3 100644 --- a/projects/start-os/ARCHITECTURE.md +++ b/projects/start-os/ARCHITECTURE.md @@ -49,8 +49,7 @@ Two Angular 22 apps live under `web/`: They are part of the single Angular workspace rooted at `../../` (the repository root) (the root `angular.json` points each project's `root` at `projects/start-os/web/...`). They consume the shared `@start9labs/shared` and `@start9labs/marketplace` libs -from the shared TypeScript modules at `../../shared-libs/ts-modules` and the SDK -base from `../start-sdk`. The frontend talks to +from the shared TypeScript modules at `../../shared-libs/ts-modules`. The frontend talks to the backend exclusively over JSON-RPC, with reactive state via Patch-DB. `web/patchdb-ui-seed.json` / `patchdb-ui-seed.beta.json` seed initial UI state @@ -70,8 +69,7 @@ and [AGENTS](container-runtime/AGENTS.md) — read those before editing it. `backup-fs/` is the `startos-backup-fs` crate (a workspace member): an encrypted, erasure-coded FUSE filesystem used for StartOS backups. It builds to the `startos-backup-fs` binary (installed as `/usr/bin/startos-backup-fs` and -`mount.backup-fs`). It was migrated into the monorepo from the former -`Start9Labs/start-fs` repo and is no longer an external git dependency. +`mount.backup-fs`). ## Systemd units and cgroups @@ -137,5 +135,5 @@ resolving, so the UI is always eventually consistent with the backend. ## Further reading - [../../shared-libs/crates/start-core](../../shared-libs/crates/start-core) — Rust backend -- [../../shared-libs/ts-modules](../../shared-libs/ts-modules) — shared TypeScript modules + workspace (currently the Angular libs `shared` and `marketplace`) +- [../../shared-libs/ts-modules](../../shared-libs/ts-modules) — shared TypeScript modules + workspace - [container-runtime/ARCHITECTURE.md](container-runtime/ARCHITECTURE.md) — runtime diff --git a/projects/start-os/container-runtime/AGENTS.md b/projects/start-os/container-runtime/AGENTS.md index 87eeb0ba0..c57ad0ad7 100644 --- a/projects/start-os/container-runtime/AGENTS.md +++ b/projects/start-os/container-runtime/AGENTS.md @@ -29,7 +29,7 @@ Tests are Jest + `ts-jest` (`jest.config.js`, `rootDir: ./src`). `mime` is mocke ## Gotchas -- **Depends on the _built_ SDK at `../../start-sdk/dist`** (declared in `package.json` as `"@start9labs/start-sdk": "file:../../start-sdk/dist"`) **and on `@start9labs/start-core` at `../../../shared-libs/ts-modules/start-core/dist`** (for what were the deep `base/lib/...` imports). Editing `projects/start-sdk/` or `shared-libs/ts-modules/start-core/` source alone has no effect here — rebuild first: `cd projects/start-sdk && make bundle` (which builds start-core and bundles it). The Makefile target `projects/start-os/container-runtime/package-lock.json` also depends on `projects/start-sdk/dist/package.json`, so a stale SDK can break `npm ci`/`check`/`test`. +- **Depends on the _built_ SDK at `../../start-sdk/dist`** (declared in `package.json` as `"@start9labs/start-sdk": "file:../../start-sdk/dist"`) **and on `@start9labs/start-core` at `../../../shared-libs/ts-modules/start-core/dist`**. Editing `projects/start-sdk/` or `shared-libs/ts-modules/start-core/` source alone has no effect here — rebuild first: `cd projects/start-sdk && make bundle` (which builds start-core and bundles it). The Makefile target `projects/start-os/container-runtime/package-lock.json` also depends on `projects/start-sdk/dist/package.json`, so a stale SDK can break `npm ci`/`check`/`test`. - **Formatting is the root prettier config** (`.prettierrc.json` at the repo root), applied via `make format` / `make web-format` from the repo root. Never run prettier from inside this directory: the root `.prettierignore` (which protects `__fixtures__/`) only applies when prettier runs from the root cwd. - **`CLAUDE.md` is just `@AGENTS.md`** — edit this file, not `CLAUDE.md`. @@ -38,7 +38,3 @@ Tests are Jest + `ts-jest` (`jest.config.js`, `rootDir: ./src`). `mime` is mocke - Compiled JS is installed into the container at `/usr/lib/startos/init/index.js` (the systemd unit runs `start-container pipe-wrap node … /usr/lib/startos/init/index.js`). - `update-image-local.sh` mounts the **repo root** into `start9/build-env` (at `/root/start-os`) and runs `update-image.sh` inside it. `update-image.sh` `cd`s to its own dir (`projects/start-os/container-runtime/`), so it reaches the repo-root build output three levels up — it copies `start-container` from `../../../target/-unknown-linux-musl/release/`. - The squashfs lands at `rootfs..squashfs` and is installed to `/usr/lib/startos/container-runtime/rootfs.squashfs`. - -## Stale-path note (monorepo) - -Pre-monorepo docs referenced `core/`, `sdk/`, `web/`, `patch-db/`, `container-runtime/` at the repo root. Current locations: host lib `shared-libs/crates/start-core`, SDK `projects/start-sdk`, Angular `shared-libs/ts-modules` + product `web/` dirs, this runtime `projects/start-os/container-runtime`, first-party `shared-libs/crates/patch-db`. diff --git a/projects/start-registry/AGENTS.md b/projects/start-registry/AGENTS.md index 0d32f6d42..8e6f87d8d 100644 --- a/projects/start-registry/AGENTS.md +++ b/projects/start-registry/AGENTS.md @@ -35,7 +35,7 @@ Feature flags are forwarded to `start-core`: `beta`, `console`, `dev`, `test`, ` - **Don't put logic here.** New registry behavior belongs in `shared-libs/crates/start-core/src/registry/`. This crate should stay a wrapper. - **`registrybox` (bin) vs `start-registry`/`start-registryd` (install names).** The Cargo bin is `registrybox`; the runtime names are symlinks created at install time. The service file references `/usr/bin/start-registryd`, which only exists after `start-registry-install` symlinks it. -- **Version:** `start-registry` is versioned **independently** in `Cargo.toml` (currently `1.0.0`), no longer tied to the StartOS release line. The `.deb` version and `basename.sh` read it straight from the manifest; bump it on its own cadence. +- **Version:** `start-registry` is versioned **independently** in `Cargo.toml`, no longer tied to the StartOS release line. The `.deb` version and `basename.sh` read it straight from the manifest; bump it on its own cadence. - **`registry_api` is shared by server and CLI.** Adding a subcommand in `registry/mod.rs` with `with_call_remote::()` exposes it both over RPC and through the `start-registry` CLI. - **Auth:** the RPC route uses local + signature auth; admin-only commands (e.g. metrics) are tagged `with_metadata("admin", true)`. - **Cross-platform builds.** CI builds musl targets for x86_64/aarch64/riscv64; local `cargo check` is host-only, so platform-specific breaks can slip through (verify against `start-core` CI when touching deps/platform APIs). diff --git a/projects/start-registry/ARCHITECTURE.md b/projects/start-registry/ARCHITECTURE.md index d13effbe8..c6447d093 100644 --- a/projects/start-registry/ARCHITECTURE.md +++ b/projects/start-registry/ARCHITECTURE.md @@ -6,8 +6,6 @@ `start-registry` lives at `projects/start-registry/` and is the product wrapper for the registry server/CLI (the `registrybox` bin + systemd unit). Its real implementation lives in `shared-libs/crates/start-core` (`src/bins/registry.rs` + `src/registry/`), and its browsing UI is `@start9labs/marketplace` (`shared-libs/ts-modules/marketplace/`). See the root [`ARCHITECTURE.md`](../../ARCHITECTURE.md) for the overall monorepo layout. -All five product binaries (`startbox`, `start-container`, `start-cli`, `registrybox`, `tunnelbox`) share the one Cargo workspace and depend on `start-core`. - ## Binary: `registrybox` `src/main.rs` builds a `MultiExecutable` (from `start_core::bins`) and registers two entry points: @@ -75,7 +73,7 @@ Package and OS indexes (`registry/package/index.rs`, `registry/os/index.rs`) hol ## Frontend -The registry has no bundled UI of its own; the browsing/search/download UI is the shared Angular library **`@start9labs/marketplace`** at `shared-libs/ts-modules/marketplace/`. App projects (StartOS web, etc.) consume that library and point it at a registry's RPC endpoints. The library is source-consumed via tsconfig paths within the `shared-libs/ts-modules` workspace of shared TypeScript modules (which currently holds the Angular libs `shared` and `marketplace`). +The registry has no bundled UI of its own; the browsing/search/download UI is the shared Angular library **`@start9labs/marketplace`** at `shared-libs/ts-modules/marketplace/`. App projects (StartOS web, etc.) consume that library and point it at a registry's RPC endpoints. The library is source-consumed via tsconfig paths within the `shared-libs/ts-modules` workspace of shared TypeScript modules. ## Further reading diff --git a/projects/start-registry/CONTRIBUTING.md b/projects/start-registry/CONTRIBUTING.md index d46078fce..0587bfa23 100644 --- a/projects/start-registry/CONTRIBUTING.md +++ b/projects/start-registry/CONTRIBUTING.md @@ -62,7 +62,6 @@ Make sure `make start-registry-format-check` is clean before opening a PR. - **Comments:** default to none; clear names over prose. A comment is for a non-obvious _why_ only — one short line. - **API additions:** add subcommands in `registry/mod.rs`; use `with_call_remote::()` to expose them to the `start-registry` CLI and `with_about(...)` for help text. Tag admin-only commands with `with_metadata("admin", true)`. - **Schema changes:** changing `RegistryDatabase` / index types requires a migration in `shared-libs/crates/start-core/src/registry/migrations`. -- **Version:** `Cargo.toml` `version` (with `# VERSION_BUMP`) tracks the OS release line — don't bump it independently. ## Docs are part of the change diff --git a/projects/start-sdk/AGENTS.md b/projects/start-sdk/AGENTS.md index 1f665a586..671404bbe 100644 --- a/projects/start-sdk/AGENTS.md +++ b/projects/start-sdk/AGENTS.md @@ -2,7 +2,7 @@ The TypeScript SDK (`@start9labs/start-sdk`) for building StartOS service packages. Lives at `projects/start-sdk/` inside the start-technologies monorepo. One npm package plus the packaging build wrapper and the packaging mdbook. `CLAUDE.md` is a one-line `@AGENTS.md` import. -This file is **both** the contribution guide and the agent/dev operating rules for this scope — how to set up, build, test, and release the SDK, plus the gotchas. It has no `CONTRIBUTING.md`: this scope's was folded in here (the rest of the monorepo still carries one per scope; that migration is in progress). See [`ARCHITECTURE.md`](ARCHITECTURE.md) for how the SDK is structured — modules, data flow, the build pipeline, and the design patterns (builder chains, effects-as-capabilities, manifest type threading). If you are building a service package _using_ the SDK rather than developing the SDK itself, you want the [packaging docs](https://docs.start9.com/packaging). +This file is **both** the contribution guide and the agent/dev operating rules for this scope — how to set up, build, test, and release the SDK, plus the gotchas. It has no `CONTRIBUTING.md`: this scope's was folded in here. See [`ARCHITECTURE.md`](ARCHITECTURE.md) for how the SDK is structured — modules, data flow, the build pipeline, and the design patterns (builder chains, effects-as-capabilities, manifest type threading). If you are building a service package _using_ the SDK rather than developing the SDK itself, you want the [packaging docs](https://docs.start9.com/packaging). **Read up the tree first.** These docs are hierarchical: before working here, read the `AGENTS.md` in each enclosing directory up to the repo root (and their `ARCHITECTURE.md` / `CONTRIBUTING.md` where relevant). This file covers only what is specific to this scope and does not repeat rules already stated higher up — commit/PR conventions live in the root [`CONTRIBUTING.md`](../../CONTRIBUTING.md). @@ -25,7 +25,6 @@ Node.js v22+ (nvm recommended), npm, and GNU Make. | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `make node_modules` | `npm ci` | | `make bundle` | build only: build `@start9labs/start-core` (prerequisite), compile SDK → `dist/`. Deliberately does **not** run `test` or `check-fmt` — see Gotchas | -| `make dist` | compile SDK (depends on start-core) | | `make test` | jest | | `make check` | `tsc --noEmit` | | `make fmt` / `make check-fmt` | Prettier write / check on all `.ts` | diff --git a/projects/start-sdk/ARCHITECTURE.md b/projects/start-sdk/ARCHITECTURE.md index ca6babc5e..6deac5abe 100644 --- a/projects/start-sdk/ARCHITECTURE.md +++ b/projects/start-sdk/ARCHITECTURE.md @@ -24,7 +24,7 @@ The Start SDK builds on a shared core library to form a layered architecture: ** └─────────────────────────────────────────────────────────────┘ ``` -The SDK follows [Semantic Versioning](https://semver.org/) and is versioned independently of StartOS (the current `@start9labs/start-sdk` 2.0.10 targets StartOS 0.4.0). Each `CHANGELOG.md` heading records the SDK version and the StartOS release it targets. +The SDK follows [Semantic Versioning](https://semver.org/) and is versioned independently of StartOS. Each `CHANGELOG.md` heading records the SDK version and the StartOS release it targets. ## Place in the monorepo @@ -176,7 +176,7 @@ Parser and verifier for `.s9pk` service package archives: ### Utilities (`shared-libs/ts-modules/start-core/lib/util/`) -~28 utility modules including: +Utility modules including: **Reactive subscription wrappers** — Each wraps an Effects callback-based method into a consistent reactive API: @@ -258,7 +258,7 @@ Features: - Graceful shutdown with configurable signals and timeouts - One-shot commands that run before daemons start -Internally the builder is record-then-materialize: `.addDaemon()` appends a recorded entry, `Daemons.build()` walks the entries to construct `HealthDaemon`s with correct dependency wiring and runs `updateStatus()`. Side-effects start at `build()`, so the timing is identical to the prior eager builder for `setupMain` users. +Internally the builder is record-then-materialize: `.addDaemon()` appends a recorded entry, `Daemons.build()` walks the entries to construct `HealthDaemon`s with correct dependency wiring and runs `updateStatus()`. Side-effects start at `build()`. **`Daemons.dynamic`** makes the daemon set a reactive function of on-disk state. `main` is always `setupMain`; `Daemons.dynamic(effects, fn)` returns a `DaemonsReconciler` — a `T.DaemonBuildable`, exactly like a static `Daemons.of(...)` chain — which you return from `setupMain`. The builder `fn` returns a regular `Daemons.of(...).addDaemon(...)` chain; the reconciler diffs its entries against the running set on every `effects.constRetry` trigger. Inside the builder, `constRetry` is bound to a rerun-and-reconcile rather than `effects.restart()`, so a change reconciles in place and the service stays `running`: @@ -472,6 +472,5 @@ The manifest type flows through the entire SDK via generics. When you call `Star ## Further reading - [README.md](README.md) — overview and quickstart -- [AGENTS.md](AGENTS.md) — build, test, release, and contribution workflow - [AGENTS.md](AGENTS.md) — agent/dev instructions (`CLAUDE.md` is a one-line `@AGENTS.md` import) - [Packaging docs](https://docs.start9.com/packaging) — the developer-facing reference (mdbook in `docs/`) diff --git a/projects/start-wrt/CONTRIBUTING.md b/projects/start-wrt/CONTRIBUTING.md index f17ae16c3..cae4cb753 100644 --- a/projects/start-wrt/CONTRIBUTING.md +++ b/projects/start-wrt/CONTRIBUTING.md @@ -111,8 +111,7 @@ rebuilds. Every setup run: provide (`dl/`, `feeds/`, `build_dir/`, `staging_dir/`, `bin/`, `files/`, `.config`, signing keys, …) is carried over, so caches and staged files are preserved. 2. Applies [`openwrt-patches/`](openwrt-patches/) with `patch -p1` — the Start9 modifications - to upstream files (currently 3 small build-infra patches for the git-cloned vendor kernel - - a 6.18 module rename). + to upstream files. 3. Rsyncs [`openwrt-overlay/`](openwrt-overlay/) over the tree — the _added_ files (mirroring upstream layout): `target/linux/spacemit/` (the K1 target, including its `patches-6.18/` kernel patches), `package/boot/{opensbi,uboot}-spacemit/`, the generic diff --git a/projects/start-wrt/backend/AGENTS.md b/projects/start-wrt/backend/AGENTS.md index 5e5114d1c..744fa57e5 100644 --- a/projects/start-wrt/backend/AGENTS.md +++ b/projects/start-wrt/backend/AGENTS.md @@ -11,11 +11,10 @@ crates are members of the **root** Cargo workspace (build with `cargo build -p s - Run from the repo root, **always `-p`-scoped**: `cargo test -p startwrt-core -p uciedit -p uciedit_macros` (or `make start-wrt-test` to run the same set inside the `start9/cargo-zigbuild` container, mirroring `start-core-test`). -- **Footgun:** a bare `cargo test` — including running it from `backend/` (which no longer has its - own workspace `Cargo.toml`) — tests the **entire** monorepo and tries to build +- **Footgun:** a bare `cargo test` — including running it from `backend/` — tests the **entire** monorepo and tries to build `startos-backup-fs`→`fuser`, whose build script fails on a host lacking FUSE dev libs. start-wrt's own crates are fuser-free, so scope with `-p`. -- Coverage is mostly in `startwrt-core` (~430 inline `#[tokio::test]`/`#[test]`), with the focused +- Coverage is mostly in `startwrt-core` (inline `#[tokio::test]`/`#[test]`), with the focused UCI parser suite in `uciedit/src/tests.rs`. ## Operating rules diff --git a/projects/start-wrt/backend/ARCHITECTURE.md b/projects/start-wrt/backend/ARCHITECTURE.md index bd4bf624e..d44d86091 100644 --- a/projects/start-wrt/backend/ARCHITECTURE.md +++ b/projects/start-wrt/backend/ARCHITECTURE.md @@ -109,7 +109,7 @@ backup # Backup create/restore (via continuations) diagnostics # Diagnostic bundle creation -uci # Generic UCI get/set/edit (legacy, being replaced) +uci # Generic UCI get/set/edit (legacy) ├─ get ├─ set └─ edit @@ -119,7 +119,7 @@ file # Generic file read/write (legacy) dir └─ get -exec # Shell command execution (being phased out) +exec # Shell command execution ``` ## Modules diff --git a/projects/start-wrt/backend/CONTRIBUTING.md b/projects/start-wrt/backend/CONTRIBUTING.md index e7353311a..06561afc1 100644 --- a/projects/start-wrt/backend/CONTRIBUTING.md +++ b/projects/start-wrt/backend/CONTRIBUTING.md @@ -146,7 +146,7 @@ Run from the repo root, scoped with `-p` (a bare `cargo test` tests the whole mo `fuser` on a bare host — see Getting Started): ```bash -cargo test -p startwrt-core # Handler tests — the bulk of coverage (~430 tests) +cargo test -p startwrt-core # Handler tests — the bulk of coverage cargo test -p uciedit # UCI parser tests cargo test -p startwrt-core -p uciedit -p uciedit_macros # everything make start-wrt-test # all of the above, containerized (mirrors start-core-test) diff --git a/projects/start-wrt/web/CONTRIBUTING.md b/projects/start-wrt/web/CONTRIBUTING.md index 0ae35bab1..fcf453c57 100644 --- a/projects/start-wrt/web/CONTRIBUTING.md +++ b/projects/start-wrt/web/CONTRIBUTING.md @@ -157,7 +157,7 @@ See `routes/published-ports/` for the best complete example of the table + dialo When you're unsure how to use a Taiga component: 1. **Check existing code** — search the codebase for usage examples. -2. **Fetch llms-full.txt** — `https://taiga-ui.dev/llms-full.txt` has all components with code examples (~2200 lines). For Claude Code: `WebFetch url=https://taiga-ui.dev/llms-full.txt prompt="How to use TuiTextfield with a select dropdown"`. +2. **Fetch llms-full.txt** — `https://taiga-ui.dev/llms-full.txt` has all components with code examples. For Claude Code: `WebFetch url=https://taiga-ui.dev/llms-full.txt prompt="How to use TuiTextfield with a select dropdown"`. 3. **MCP server (beta)** — `taiga-family/taiga-ui-mcp` exposes `get_list_components` (fuzzy search) and `get_component_example` (docs + code). Add to your Claude config: ```json diff --git a/shared-libs/AGENTS.md b/shared-libs/AGENTS.md index 2838d0c67..e7e55fbf6 100644 --- a/shared-libs/AGENTS.md +++ b/shared-libs/AGENTS.md @@ -43,8 +43,7 @@ make web-format-check # prettier check across the Angular workspa ## Gotchas -- **No code lives directly in `shared-libs/`** — only the two sub-dirs. Don't add - files at this level beyond these doc files. +- **No code lives directly in `shared-libs/`** — only the two sub-dirs. - **start-core is one crate in one workspace.** Build it by package name (`-p start-core`), not by `cd`-ing and running a bare `cargo build`. There is a single root `Cargo.toml` / `Cargo.lock`. @@ -60,8 +59,7 @@ make web-format-check # prettier check across the Angular workspa - **`build:deps` is a prerequisite.** `@start9labs/start-core` resolves to `shared-libs/ts-modules/start-core/dist` and `patch-db-client` to `shared-libs/crates/patch-db/client` (from the workspace root); both must be built before typecheck/build will succeed. -- **patch-db is a first-party crate** at repo-root `shared-libs/crates/patch-db/` (not the old - root `patch-db/`). start-core consumes its Rust `core`; web consumes its +- **patch-db is a first-party crate** at repo-root `shared-libs/crates/patch-db/`. start-core consumes its Rust `core`; web consumes its TS `client`. - **Web UI work follows the `start9-frontend` skill** at the repo root (`.claude/skills/start9-frontend/`) — see `ts-modules/AGENTS.md`. diff --git a/shared-libs/CONTRIBUTING.md b/shared-libs/CONTRIBUTING.md index 192fa0502..da0949ac9 100644 --- a/shared-libs/CONTRIBUTING.md +++ b/shared-libs/CONTRIBUTING.md @@ -38,7 +38,7 @@ cd shared-libs/crates/start-core && ./run-tests.sh ## ts-modules (shared TypeScript modules) -Shared TypeScript modules; the current contents are Angular libraries, built +Shared TypeScript modules, built through the single Angular workspace rooted at the repo root. ```bash diff --git a/shared-libs/crates/exver/AGENTS.md b/shared-libs/crates/exver/AGENTS.md index 75cd80113..2641021d1 100644 --- a/shared-libs/crates/exver/AGENTS.md +++ b/shared-libs/crates/exver/AGENTS.md @@ -10,7 +10,7 @@ the workflow. ## Layout -- `src/lib.rs` — crate root. Re-exports `exver::*` and `emver`; gates `wasm` and the test module. +- `src/lib.rs` — crate root. Re-exports `exver::*` and `emver`; gates the test module. - `src/exver.rs` — all core types and logic: `Version`, `ExtendedVersion`, `VersionRange`, `ParseError`, `PreReleaseSegment`, the `Operator` constants (`EQ`/`NEQ`/`GT`/`GTE`/`LT`/`LTE`), the `AnyRange`/`AllRange` monoid wrappers, the Pest `Grammar`, `FromStr`/`Display`/`Serialize` diff --git a/shared-libs/crates/jsonpath/AGENTS.md b/shared-libs/crates/jsonpath/AGENTS.md index c30c8bbc3..f0a2af14d 100644 --- a/shared-libs/crates/jsonpath/AGENTS.md +++ b/shared-libs/crates/jsonpath/AGENTS.md @@ -34,7 +34,7 @@ how to contribute. [README.md](README.md) is the usage/API reference. new FFI here. - `wasm/`, `benchmark/` — auxiliary build targets (separate Cargo manifests, own READMEs). `lua/`, `docs/`, `*.sh` build scripts are inherited from the original project and unused by the Rust crate. -- `tests/` — one integration-test crate (11 modules: `array_filter`, `common`, `filter`, +- `tests/` — one integration-test crate (`array_filter`, `common`, `filter`, `jsonpath_examples`, `lib`, `op`, `paths`, `precompile`, `readme`, `return_type`, `selector`). ## Build & test (run from the repo root) @@ -54,8 +54,7 @@ cargo test -p jsonpath_lib selector_delete # a single test by name fully diverged; there is no upstream to track or reconcile with — treat it as first-party and edit freely. The largest divergence is operating on `imbl_value::Value` instead of `serde_json::Value`. - **Edition 2015.** `Cargo.toml` sets no `edition`, so it defaults to 2015 — old `extern crate` - syntax, two-element `use {a, b}` paths, etc. Pre-existing warnings (unused imports, lifetime - elisions, unused fields) predate the divergence and are not critical. + syntax, two-element `use {a, b}` paths, etc. - **Package name ≠ dir name.** The crate is `jsonpath_lib`; cargo `-p` flags must use that. - **`cdylib` + `rlib`.** The lib emits both crate types; the `cdylib` feeds the `wasm/` bindings. Changing public types may require rebuilding those bindings. diff --git a/shared-libs/crates/jsonpath/CONTRIBUTING.md b/shared-libs/crates/jsonpath/CONTRIBUTING.md index 33af8d2c2..139a37835 100644 --- a/shared-libs/crates/jsonpath/CONTRIBUTING.md +++ b/shared-libs/crates/jsonpath/CONTRIBUTING.md @@ -40,7 +40,7 @@ cargo test -p jsonpath_lib --test '*' # integration tests only (tests/) cargo test -p jsonpath_lib selector_delete # a single test by name ``` -The `tests/` directory is a single integration-test crate with 11 modules; doc tests run from the +The `tests/` directory is a single integration-test crate; doc tests run from the examples in `src/lib.rs` and `README.md`. ## Formatting @@ -50,8 +50,7 @@ make start-core-format # format the shared Rust crates (incl. jsonpath) make start-core-format-check # CI-style read-only check ``` -The workspace uses nightly rustfmt. Note this crate carries pre-existing warnings (unused imports, -lifetime elisions) that predate the divergence; don't churn unrelated lines to silence them. +The workspace uses nightly rustfmt. ## Working in this crate diff --git a/shared-libs/crates/pi-beep/AGENTS.md b/shared-libs/crates/pi-beep/AGENTS.md index 309c49d18..2f261a63a 100644 --- a/shared-libs/crates/pi-beep/AGENTS.md +++ b/shared-libs/crates/pi-beep/AGENTS.md @@ -2,7 +2,7 @@ A tiny first-party bin in the start-technologies monorepo at `shared-libs/crates/pi-beep` (Cargo package `pi-beep`, binary `pi-beep`). It reimplements the Unix `beep` command using the Raspberry Pi's PWM -hardware exposed through `/sys/class/pwm/`. The whole crate is a single ~117-line `src/main.rs` whose +hardware exposed through `/sys/class/pwm/`. The whole crate is a single `src/main.rs` whose only dependency is `clap`. `CLAUDE.md` is a one-line `@AGENTS.md` import; edit this file instead. See [ARCHITECTURE.md](ARCHITECTURE.md) and [CONTRIBUTING.md](CONTRIBUTING.md). @@ -30,7 +30,7 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) and [CONTRIBUTING.md](CONTRIBUTING.md). cargo build -p pi-beep # host build cargo build -p pi-beep --target=aarch64-unknown-linux-musl # cross-compile for RPi (needs rust-zig-builder) ARCH=aarch64 PROFILE=release ./shared-libs/crates/pi-beep/build-pi-beep.sh # what the OS image build runs -cargo test -p pi-beep # no tests defined; passes trivially +cargo test -p pi-beep ``` ## Gotchas diff --git a/shared-libs/crates/pi-beep/CONTRIBUTING.md b/shared-libs/crates/pi-beep/CONTRIBUTING.md index ef1710998..fb6fc9e22 100644 --- a/shared-libs/crates/pi-beep/CONTRIBUTING.md +++ b/shared-libs/crates/pi-beep/CONTRIBUTING.md @@ -37,8 +37,7 @@ Run from the repo root: cargo test -p pi-beep ``` -There are no tests in the source today (the logic is direct sysfs I/O that only exercises on RPi -hardware). If you add testable logic, add unit tests alongside it. +If you add testable logic, add unit tests alongside it. ## Formatting diff --git a/shared-libs/crates/rpc-toolkit/CONTRIBUTING.md b/shared-libs/crates/rpc-toolkit/CONTRIBUTING.md index 74707d038..e9ec8219b 100644 --- a/shared-libs/crates/rpc-toolkit/CONTRIBUTING.md +++ b/shared-libs/crates/rpc-toolkit/CONTRIBUTING.md @@ -26,8 +26,7 @@ cargo build -p rpc-toolkit --features ts-rs cargo build -p rpc-toolkit --no-default-features # JSON-only (no CBOR) ``` -This is **not** a vendored fork — it is a first-party crate consumed via a path dependency -(currently by `start-core`). When you change a public API, update the consumers in the same change +This is **not** a vendored fork — it is a first-party crate consumed via a path dependency. When you change a public API, update the consumers in the same change and check `cargo build -p start-core` still passes. ## Testing @@ -43,12 +42,9 @@ CLI/server bindings, exercise it there. ## Formatting -This crate ships a `rustfmt.toml` (`group_imports = "StdExternalCrate"`, -`imports_granularity = "Module"`). Format with the shared Rust make target from the repo root: +Format with the shared Rust make target from the repo root: ```bash make start-core-format # format all shared Rust crates (incl. rpc-toolkit) make start-core-format-check # CI read-only check ``` - -The import-grouping options in `rustfmt.toml` are applied either way. diff --git a/shared-libs/crates/start-core/AGENTS.md b/shared-libs/crates/start-core/AGENTS.md index a7001657a..d81884a5c 100644 --- a/shared-libs/crates/start-core/AGENTS.md +++ b/shared-libs/crates/start-core/AGENTS.md @@ -20,8 +20,7 @@ Topical references: [rpc-toolkit.md](rpc-toolkit.md), [patchdb.md](patchdb.md), `MultiExecutable`. Don't add a new top-level binary here — add an entrypoint and enable it from the product crate. - Generated TS lands in `bindings/` (gitignored, regenerated by `make start-core-ts-bindings`); never hand-edit it. -- The whole backend is one crate `src/` tree — there are no longer separate `helpers`/`models` - sibling crates, and there is no `js-engine`. +- The whole backend is one crate `src/` tree. ## Build & test (run from the repo root) diff --git a/shared-libs/crates/yasi/AGENTS.md b/shared-libs/crates/yasi/AGENTS.md index f05ff35e1..6e4a36185 100644 --- a/shared-libs/crates/yasi/AGENTS.md +++ b/shared-libs/crates/yasi/AGENTS.md @@ -15,7 +15,7 @@ contributor workflow. internal `StringRepr` enum (`Heap`/`Stack`/`Static`), `StringRef` table entry, `DisplayHasher` and `DisplayEq` (Display-based hashing/equality), `TableString` (the heap-owned string with the table-eviction `Drop`), and the `lazy_static` global `TABLE: RwLock>`. - Holds the two unit tests, including the `intern → drop` deadlock regression test. + Holds the unit tests, including the `intern → drop` deadlock regression test. - `src/serde.rs` — feature-gated (`serde`): `Serialize`/`Deserialize` for `InternedString` via an `InternedStringVisitor` (deserializes any string/bytes form by interning it). - `src/ts_rs.rs` — feature-gated (`ts-rs`): `ts_rs::TS` impl that reports the type as `"string"`, @@ -35,7 +35,7 @@ make start-core-format-check # CI read-only format check ## Gotchas - `Cargo.toml` declares `edition = "2024"` and the code uses 2024 features (let-chains in `eq` - closures). Build with a toolchain that supports edition 2024; sibling `exver` is still on 2021. + closures). Build with a toolchain that supports edition 2024. - Features `serde` and `ts-rs` are **not** in `default`. Consumers opt in (e.g. `imbl-value` enables `serde` and forwards `ts-rs`); plain `cargo test -p yasi` exercises neither module. - Strings of 20 bytes or fewer (`STACK_STR_SIZE`) are inlined in `StringRepr::Stack` and never diff --git a/shared-libs/ts-modules/CONTRIBUTING.md b/shared-libs/ts-modules/CONTRIBUTING.md index 3a8caef44..bcee9b909 100644 --- a/shared-libs/ts-modules/CONTRIBUTING.md +++ b/shared-libs/ts-modules/CONTRIBUTING.md @@ -100,16 +100,6 @@ A pre-commit hook runs `lint-staged` (prettier on staged files). - Polish - German - French - ### Adding a new translation