From f1613ac94ad18fdff54d468824efa5cb73db0d1c Mon Sep 17 00:00:00 2001 From: Daniel Bernstein Date: Fri, 18 Sep 2026 14:03:37 -0700 Subject: [PATCH 1/3] Say what the core/ and scripts/ deprecations actually mean Both markers were written as "deprecated - no new code" when CLAUDE.md was first added in 21df3c5d9. Read literally, neither is true, and reviewers acting on the literal reading keep asking for moves that have nowhere to go. `scripts/` has no replacement. `[project.scripts]` holds exactly one entry and it resolves into that package; there is no cli/ package, click app or `palace` command; and of the ~74 wrappers in bin/, 50 import palace.manager.scripts directly and 16 more subclass Script through the integration packages. Five new Script subclasses and five new bin/ wrappers have landed since the marker was written. What the deprecation is actually protecting is business logic, which now goes in celery/tasks/ with a thin dispatcher here. `core/` is genuinely being drained -- net -2,001 lines over the last year, as coverage providers, monitors and facets came out. But `core/classifier/` is net +131 over the same period and is the only part still taking behaviour changes. Nothing outside it defines classification logic, and there is no candidate home: packages/ holds only palace-opds and palace-util, and service/ is DI wiring. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9b776e9219..26ba6470dc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -60,11 +60,19 @@ This repository is a [`uv` workspace](https://docs.astral.sh/uv/concepts/project - `/admin` - Administrative API endpoints for the web dashboard - `/celery` - Background worker processes and task definitions - `/core` - Legacy miscellaneous components (**deprecated - no new code**) + - Exception: `/core/classifier` is the active home of classification logic (the BISAC + rulesets and code table, keyword matching, `WorkClassifier`). It has no replacement + elsewhere in the tree, so classification changes belong here. - `/customlists` - CLI tools for managing custom book collections - `/data_layer` - Pydantic models for content import and validation - `/feed` - OPDS (Open Publication Distribution System) feed generation - `/integration` - Third-party service integrations and content provider APIs - - `/scripts` - Legacy CLI utilities (**deprecated - no new code**) + - `/scripts` - Legacy CLI utilities (**deprecated - put new logic in `/celery/tasks`**) + - The package is deprecated for *logic*, not for entry points. A thin `Script` subclass + here plus a `bin/` wrapper is still the only supported way to run something on demand, + and is still the expected pattern for dispatching a Celery task by hand. There is no + replacement framework: `palace-startup-task` is the only console script the project + ships, and it resolves into this package. - `/search` - OpenSearch integration and indexing logic - `/service` - Dependency injection container and service layer - `/sqlalchemy` - Database models and schema definitions From 73fe1b0afb22cb0a8440ac51c95c08c6f5a52b7c Mon Sep 17 00:00:00 2001 From: dbernstein Date: Wed, 23 Sep 2026 16:41:21 -0700 Subject: [PATCH 2/3] Update CLAUDE.md Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 26ba6470dc..66dd4abb27 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -69,7 +69,7 @@ This repository is a [`uv` workspace](https://docs.astral.sh/uv/concepts/project - `/integration` - Third-party service integrations and content provider APIs - `/scripts` - Legacy CLI utilities (**deprecated - put new logic in `/celery/tasks`**) - The package is deprecated for *logic*, not for entry points. A thin `Script` subclass - here plus a `bin/` wrapper is still the only supported way to run something on demand, + here plus a `bin/` wrapper is still a supported way to run something on demand, and is still the expected pattern for dispatching a Celery task by hand. There is no replacement framework: `palace-startup-task` is the only console script the project ships, and it resolves into this package. From 35e3f3fdf34ca9b970c77061628001681440cf9c Mon Sep 17 00:00:00 2001 From: Daniel Bernstein Date: Fri, 25 Sep 2026 12:33:04 -0700 Subject: [PATCH 3/3] Point both exceptions at the right directory Review on #3749 caught two places where the new wording sends a reader somewhere the thing is not. "A thin Script subclass *here*" reads as /scripts only, but nine modules define integration-local Script subclasses next to the integration they drive -- bibliotheca, boundless, overdrive, the five opds variants, and discovery/registration_script. Left as written it makes those look misplaced and would push a new vendor script into /scripts, which is the opposite of what this change is for. The BISAC code table is not in /core/classifier either. bisac.py:261 loads it from /resources/classifier via classifier_resources_dir(), alongside dewey_1000.json and lcc_one_level.json. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 66dd4abb27..53492c4df2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -61,18 +61,20 @@ This repository is a [`uv` workspace](https://docs.astral.sh/uv/concepts/project - `/celery` - Background worker processes and task definitions - `/core` - Legacy miscellaneous components (**deprecated - no new code**) - Exception: `/core/classifier` is the active home of classification logic (the BISAC - rulesets and code table, keyword matching, `WorkClassifier`). It has no replacement - elsewhere in the tree, so classification changes belong here. + rulesets, keyword matching, `WorkClassifier`; the code tables they load live in + `/resources/classifier`). It has no replacement elsewhere in the tree, so + classification changes belong here. - `/customlists` - CLI tools for managing custom book collections - `/data_layer` - Pydantic models for content import and validation - `/feed` - OPDS (Open Publication Distribution System) feed generation - `/integration` - Third-party service integrations and content provider APIs - `/scripts` - Legacy CLI utilities (**deprecated - put new logic in `/celery/tasks`**) - The package is deprecated for *logic*, not for entry points. A thin `Script` subclass - here plus a `bin/` wrapper is still a supported way to run something on demand, - and is still the expected pattern for dispatching a Celery task by hand. There is no - replacement framework: `palace-startup-task` is the only console script the project - ships, and it resolves into this package. + (here, or alongside its integration under `/integration`) plus a `bin/` wrapper is + still a supported way to run something on demand, and is still the expected pattern + for dispatching a Celery task by hand. There is no replacement framework: + `palace-startup-task` is the only console script the project ships, and it resolves + into this package. - `/search` - OpenSearch integration and indexing logic - `/service` - Dependency injection container and service layer - `/sqlalchemy` - Database models and schema definitions