@cerebriline/core 4.100.240 → 4.100.242

package/assets/skills/README.md

@@ -0,0 +1,14 @@
+# Built-in skills
+
+The skills that ship with Cerebriline: the extension, the CLI and the SDK all
+carry this folder. One folder per skill, each with a `SKILL.md`.
+
+- `name` and `description` in the frontmatter are required here. The
+  description is all the model sees when it decides whether to load the skill.
+- `disabled: true` means the skill ships turned off. That is only the default:
+  the user's choice is kept in the global settings (`bundledSkills`), because
+  an update replaces these files.
+- A skill of the same name in the user's own or the workspace's skills folder
+  replaces the built-in one.
+
+Each skill here is listed in `docs/customization/skills.mdx` under "Built-in Skills": add a row there when adding a folder here.

package/assets/skills/build-project/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: build-project
+description: >-
+  Builds the project open in the workspace, and its Docker image when the repo
+  has a Dockerfile or a compose file. Discovers the build from the repo itself
+  (its README, CI workflow, scripts, manifest), runs it, and reports the
+  artifacts and the image tag. Use when the user asks to build or compile the
+  project or its image, or before a deploy that needs an image.
+disabled: true
+---
+
+# Skill: Build the Current Project
+
+Builds whatever repository is open in the workspace. Nothing here assumes a language, a framework, a path or a tag: every value is **discovered from the repo first**, and the repo's own way of building always wins over a generic one.
+
+Related skills, used when they are enabled; each also works alone:
+
+- `docker-compose-deploy` runs the image or stack this skill builds.
+- `run-project` builds if needed, starts the project and opens it.
+
+## Step 0: Discover how this repo is built
+
+Look, in this order, and stop at the first that answers:
+
+1. **What the repo says.** `README*`, `CONTRIBUTING*`, `docs/`, an `AGENTS.md` or similar. A documented build command is the answer.
+2. **What CI runs.** `.github/workflows/*.yml`, `.gitlab-ci.yml`, `azure-pipelines.yml`, `Jenkinsfile`. The build job is a build known to work.
+3. **Task runners.** `Makefile`, `justfile`, `Taskfile.yml`, the `scripts` in `package.json`.
+4. **The manifest**, when nothing above names a command:
+
+| Found | Install | Build |
+|---|---|---|
+| `package.json` | the manager whose lockfile exists: `npm ci`, `pnpm install --frozen-lockfile`, `yarn install --frozen-lockfile`, `bun install --frozen-lockfile` | the `build` script, with the same manager |
+| `*.sln`, `*.csproj` | `dotnet restore` | `dotnet build -c Release` |
+| `pyproject.toml`, `requirements.txt` | the tool the repo uses (`uv`, `poetry`, `pip` in a virtual environment) | usually none; `python -m build` only if it ships a package |
+| `go.mod` | — | `go build ./...` |
+| `Cargo.toml` | — | `cargo build --release` |
+| `pom.xml` | — | `mvn -B package` (use `./mvnw` if present) |
+| `build.gradle*` | — | `./gradlew build` |
+
+Also find, because the image build needs them:
+
+| Value | Where |
+|---|---|
+| Dockerfile(s) | any `Dockerfile*`, and a compose service's `build:` (`context`, `dockerfile`, `target`, `args`) |
+| Build context | the compose `build.context`, else the folder the Dockerfile's `COPY` paths are relative to; often the repo root even when the Dockerfile is in a subfolder |
+| Image name | a compose `image:`, else a name the repo's scripts or CI use, else `<repo-folder-name>` in lower case |
+| Build arguments | `ARG` lines with no default in the Dockerfile; compose `build.args` |
+
+If the repo is a monorepo, build the part the user is working on or asked for; ask only when that is not clear.
+
+## Step 1: Build the project
+
+Run the install step, then the build, from the folder the manifest is in.
+
+- Use the lockfile as it is. Do not delete it, regenerate it or upgrade dependencies to get a build through.
+- Do not install tools globally or change the machine. If a required tool or version is missing, say which and stop.
+- A build that fails on the code is a result to report with its error, not something to work around by disabling checks.
+
+Skip this step when the Dockerfile builds the project itself (a multi-stage Dockerfile that runs the install and build inside the image) and the user asked only for the image.
+
+## Step 2: Build the image
+
+Only when the repo has a Dockerfile or a compose file. First check that Docker answers: `docker info`. If it does not, say that Docker is not running and stop.
+
+**The repo has a compose file with `build:`** — let compose build it, so the context, the Dockerfile, the target and the arguments are the ones the repo defines:
+
+```
+docker compose build
+docker compose build <service>      # one service
+```
+
+Run it from the folder the compose file is in, or pass `-f <path>`.
+
+**Only a Dockerfile:**
+
+```
+docker build -f <path/to/Dockerfile> -t <image-name>:dev <build-context>
+```
+
+- `<image-name>:dev` is one name and one tag, for example `myapp:dev`. Use the same value everywhere afterwards.
+- Pass each required build argument with `--build-arg NAME=value`. Never pass a secret as a build argument; it stays in the image history.
+- If `COPY` fails with "not found", the build context is wrong, not the Dockerfile: the paths in `COPY` are relative to the context given as the last argument.
+
+## Step 3: Verify
+
+- The project build: the command exited 0 and the artifact it should produce exists (`dist/`, `bin/Release/`, `target/`, the binary).
+- The image: `docker image ls <image-name>` lists the tag just built, with a creation time of now.
+
+## Step 4: Report
+
+Say what was built, in a form the next step can use:
+
+- the build command that was run, and where;
+- the artifacts and their path;
+- the image as `<image-name>:<tag>`, or the compose services that were built;
+- the port the Dockerfile `EXPOSE`s, if any.
+
+## What goes wrong
+
+- **The image build is slow or huge.** There is no `.dockerignore`, so `node_modules`, `.git` and build output are sent as context. Say so; add one only if the user agrees.
+- **It builds locally and fails in the image.** A file the build needs is listed in `.dockerignore`, or the image has a different tool version than the machine.
+- **A different architecture is needed.** An image built on an Apple Silicon or ARM machine is `arm64`. For an `amd64` target add `--platform linux/amd64`.
+- **Compose ignores a code change.** `docker compose up` reuses an existing image; it is `docker compose build` or `up --build` that rebuilds.

package/assets/skills/docker-compose-deploy/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: docker-compose-deploy
+description: >-
+  Deploys the project open in the workspace to local Docker (Docker Desktop or
+  a local engine). Covers choosing the deployment method (docker compose up, or
+  docker run of an image built from the repo's Dockerfile), running the stack
+  or container exactly as the repo's compose file or Dockerfile defines, and
+  verifying the deployment. Use when the user asks to deploy, redeploy or tear
+  down the project's containers.
+disabled: true
+---
+
+# Skill: Deploy the Current Project to Docker Desktop
+
+This skill **deploys** the **current project** (whatever repo is open in the workspace) to **local Docker** (Docker Desktop, or a local Docker engine). It is deliberately **project-agnostic**: it first **discovers** how the repo defines its containers (compose file and/or Dockerfile + image), then stands them up and verifies them.
+
+Commands are written once where they are the same in every shell. Where PowerShell and bash differ, both forms are given: use the one for the shell you are in.
+
+> **Two deployment paths (choose based on discovery):**
+> 1. **Compose stack** — the repo ships a `docker-compose*.yml` or `compose*.yml`. Use `docker compose up -d` (preferred; the compose file encodes services, build, ports, volumes, env for you).
+> 2. **Single container** — the repo has only a Dockerfile. Build the image from it, then use `docker run` with the discovered image name, container name, ports, and env.
+
+> **Related skills** (built in; used when they are enabled, and this skill works without them):
+> - `build-project` — build the project + Docker image (the image must exist before a single-container deploy; a compose `up` builds it on demand). If it is not enabled, build the image with the `docker build` command in Step 1, Path B.
+> - `run-project` — "run the project" (deploy if needed, then open the app in the default browser). Use that one when the user wants to run/open the app.
+
+---
+
+## When to Use This Skill
+
+- You need to stand the app(s) up on local Docker Desktop the way the repo defines them.
+- You need to deploy a specific environment (Development / QA / Staging / Production) that the repo's config supports.
+- You need to redeploy after a code change in one command.
+- You need to verify the running container(s) (startup logs + HTTP reachability).
+
+---
+
+## Prerequisites
+
+1. **Docker** must be running: `docker info` succeeds. If it does not, say that Docker is not running and stop; do not try to start or install it.
+2. The image must exist (build it first if it is missing, see Path B) — or, for a compose stack, the compose file builds it on `up`.
+3. The repo must be checked out at the desired branch/tag.
+
+---
+
+## Step 0 -- Discover the Project's Deploy & Container Facts
+
+Do **not** assume any project name, framework, path, image tag, or port. **Discover them from the repo** each time:
+
+| Concern | How to discover | Command |
+|---------|-----------------|---------|
+| **Compose file** | Find any `docker-compose*.yml`/`.yaml` or `compose*.yml`/`.yaml`. If present, the compose path is preferred. | `list_files` patterns `**/docker-compose*` and `**/compose*.y*ml` |
+| **Image name** | A compose `image:`, else the name already built for this repo, else `<repo-folder-name>` in lower case. Written with its tag as `<image-name>:dev`, e.g. `myapp:dev`. | Compose / `docker image ls` |
+| **Container name(s)** | Compose service name(s); or your own `<repo-name>-<svc>` convention for a single container. | Compose `services:` keys / derive |
+| **Ports / published ports** | Read `ports:` in the compose file, or the Dockerfile `EXPOSE` lines. The **web/front-end port** (the one to open in a browser) is usually the first published port or the service named `web`. | Compose `ports:` / Dockerfile `EXPOSE` |
+| **Environment** | Compose `environment:`/`env_file`, or env vars the app reads (`NODE_ENV`, `ASPNETCORE_ENVIRONMENT`, etc.). | Compose / `.env` |
+| **Required secrets** | Compose uses `${VAR:?...}` for required secrets. Provide them from the host env / secret manager — never invent or bake them. | Compose `environment:` |
+
+> State the discovered values in your reply (especially **image name**, **container name(s)**, and **web port**): nothing is remembered between skills, so whatever runs next reads them from there.
+
+---
+
+## Step 1 -- Deploy
+
+### Path A: Compose stack (preferred when a compose file exists)
+
+```
+# From the directory that contains the compose file (commonly repo-root or docker/),
+# or from anywhere with: docker compose -f <path/to/compose-file> up -d
+docker compose up -d
+```
+
+- `up -d` builds images from `build:` where needed, creates the networks/volumes, and starts the services in dependency order.
+- To rebuild images from current source and recreate containers after a code change:
+  ```
+  docker compose up -d --build
+  ```
+- To target a single service:
+  ```
+  docker compose up -d <service-name>
+  ```
+- If `docker compose` is not a known command, the machine has the older standalone tool: use `docker-compose` with the same arguments.
+- **Required secrets:** if the compose file uses `${SOME_VAR:?SOME_VAR is required}`, set `SOME_VAR` in the shell/environment first (or provide an `.env` alongside the compose file). Docker Compose fails fast if a required variable is unset — that is the safety net.
+
+### Path B: Single container (`docker run` of an image built from the Dockerfile)
+
+Use the values discovered in Step 0 (image name, container name, host port, container port, env). Each command is one line, so it is the same in every shell:
+
+```
+# Build the image if it does not exist yet, or the source changed
+# (the last argument is the build context: the folder COPY paths are relative to)
+docker build -f <path/to/Dockerfile> -t <image-name>:dev <build-context>
+
+# Remove an earlier container of the same name. Only one this deployment created:
+# if the name belongs to something else, pick another name instead.
+docker rm -f <container-name>
+
+# One -e per variable the app needs (environment selection, connection strings, secrets)
+docker run -d --name <container-name> -p <hostPort>:<containerPort> -e <KEY>=<value> <image-name>:dev
+```
+
+`docker rm -f` prints "No such container" when there was none; that is not a failure.
+
+> Example (repo-root Dockerfile, HTTP port 8080 mapped to host 32798):
+> ```
+> docker build -t myapp:dev .
+> docker rm -f myapp
+> docker run -d --name myapp -p 32798:8080 -e NODE_ENV=production myapp:dev
+> ```
+>
+> For a stack with a front-end and backing services, prefer **Path A** (compose) — `docker run` only makes sense for a single self-contained service.
+
+---
+
+## Step 2 -- Verify the Deployment
+
+```
+# Compose stack: every service should be "running" (or "healthy")
+docker compose ps
+docker compose logs --tail 100 <service-name>
+
+# Single container
+docker ps --filter "name=<container-name>"
+docker logs --tail 100 <container-name>
+
+# Confirm the web server answers from the host
+curl -s -o /dev/null -w "%{http_code}" --retry 15 --retry-delay 2 --retry-all-errors http://localhost:<hostPort>/      # bash, zsh
+curl.exe -s -o NUL -w "%{http_code}" --retry 15 --retry-delay 2 --retry-all-errors http://localhost:<hostPort>/        # PowerShell, cmd
+```
+
+In PowerShell write `curl.exe`: plain `curl` there can be an alias for a different command that does not take these options. An app needs some seconds after its container starts, and a request sent at once fails: the `--retry` options make curl ask again for up to about half a minute, so run the check as written.
+
+A `200` or `3xx` (e.g. a redirect to login) means the web server is up; a `401` or `403` also means it is answering. Look in the logs for lines like `Now listening on:`, `Server listening on`, or the app's startup banner. Access the app at `http://localhost:<hostPort>/` (and any documented sub-route such as `/login`).
+
+> Background-service connection warnings in the logs are often **non-fatal** — the web server may still run and serve traffic. Confirm reachability over HTTP rather than assuming a log warning means the app is down.
+
+---
+
+## Step 3 -- Make a Change and Redeploy (iterative loop)
+
+```
+# Compose stack: rebuild images + recreate containers
+docker compose up -d --build
+
+# Single container: rebuild the image, then recreate the container
+docker build -f <path/to/Dockerfile> -t <image-name>:dev <build-context>
+docker rm -f <container-name>
+docker run -d --name <container-name> -p <hostPort>:<containerPort> <image-name>:dev
+```
+
+---
+
+## Step 4 -- Tear Down
+
+```
+# Compose stack (removes containers/networks; keeps named volumes by default)
+docker compose down
+
+# Single container
+docker rm -f <container-name>
+```
+
+Do not add `-v` / `--volumes` to `down`, and do not prune volumes, unless the user asks: that deletes the stack's data (databases, uploads).
+
+---
+
+## What Does NOT Work -- Universal Lessons
+
+These hold for most containerised apps regardless of framework:
+
+### HTTPS does not work out of the box in a CLI-started container
+
+Many runtime base images (`dotnet/aspnet`, `node:*-slim`) do not include development HTTPS certificates — an IDE's own "run in Docker" injects them via volume mounts, but a CLI `docker run` does not. The container often serves **HTTP only** from the CLI. Use **HTTP** (`http://localhost:<hostPort>`) for a script/CLI deployment, or mount a real certificate for the app's scheme.
+
+### Missing required environment is a silent or immediate failure
+
+If the app needs an env var/secret and it is not provided, it either **fails to start** (compose `${VAR:?}` refuses to run) or **starts but never serves** (the app waits/blocks on a missing config). Always set required env vars from the host env / secret manager before `up`/`run`, and verify over HTTP rather than trusting `docker ps` — a container can look "up" while serving nothing.
+
+### The published port and the container port are different things
+
+`-p <hostPort>:<containerPort>` maps a **host** port to the app's **container** port (the one from `EXPOSE`/the runtime default). Reach the app at the **host port**, not the container port: the host port is what you open in a browser. If the host port is already taken (`port is already allocated`), choose another host port for a single container; for a compose stack, tell the user what holds the port rather than editing the compose file or stopping something this deployment did not start.
+
+### Secrets must never be baked into the image or a committed `.env`
+
+For a production deployment, prefer environment overrides injected at run time. Never commit a new `.env` with real secrets.
+
+---
+
+## Quick Reference -- Full Working Sequence
+
+```
+# 0. Discover: compose file? image name? container name? web port? required env?
+#    - list_files for docker-compose* / compose*.y*ml / Dockerfile*
+docker info                   # Docker must answer
+
+# 1. Deploy
+cd <dir-with-compose-or-repo-root>
+docker compose up -d          # Path A: compose stack (builds on demand)
+# or (single container):
+# docker build -f <path/to/Dockerfile> -t <image-name>:dev <build-context>
+# docker rm -f <container-name>
+# docker run -d --name <container-name> -p <hostPort>:<containerPort> <image-name>:dev
+
+# 2. Verify
+docker compose ps             # or: docker ps --filter "name=<container-name>"
+docker compose logs --tail 100 <service-name>     # or: docker logs --tail 100 <container-name>
+curl -s -o /dev/null -w "%{http_code}" --retry 15 --retry-delay 2 --retry-all-errors http://localhost:<hostPort>/     # bash, zsh
+curl.exe -s -o NUL -w "%{http_code}" --retry 15 --retry-delay 2 --retry-all-errors http://localhost:<hostPort>/       # PowerShell, cmd
+
+# 3. Redeploy after a code change
+docker compose up -d --build
+
+# 4. Tear down
+docker compose down
+```
+
+---
+
+## Discovery Checklist -- Where to Find Each Value
+
+| Value | Where to find it | How to find it |
+|-------|------------------|----------------|
+| Compose file | `**/docker-compose*.y*ml`, `**/compose*.y*ml` | `list_files` with those patterns |
+| Container HTTP/web port | Compose `ports:` (host side) or Dockerfile `EXPOSE` | Read the compose file / Dockerfile |
+| Container-internal port | Compose `ports:` (container side) or Dockerfile `EXPOSE` | Read the compose file / Dockerfile |
+| Image name | Compose `image:`, or the name the image was built with | Compose / `docker image ls` |
+| Required backing services | Compose `services:` / app config binding | Read the compose file / app config |
+| Required env/secrets | Compose `environment:` (`${VAR:?...}`) / `.env` | Read the compose file |
+
+---
+
+## Key Files to Check
+
+| File | Role |
+|------|------|
+| `**/docker-compose*.y*ml`, `**/compose*.y*ml` | Services, build, ports, volumes, env — the primary source of truth for a stack deploy. |
+| `**/Dockerfile` | Multi-stage image build; `EXPOSE` ports; `ENTRYPOINT`/`CMD` (used at build time). |
+| `.env` (if any) | Environment variables / secrets referenced by the compose file. |
+| App manifest / config | Per-environment config and the runtime port/env defaults. |

package/assets/skills/librarian/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: librarian
+description: >-
+  Runs the user's Library as its librarian: catalogues ebooks and documents
+  into books on the right shelf, checks first whether a book is already there
+  or is another edition, makes books from web pages and keeps them up to date,
+  and reorganises sections, shelves and books. Use when the user asks to act
+  as a librarian, to catalogue, add, import, export, move, rename, merge or
+  remove books, to make a book from links or on a topic, or to check a book
+  for updates.
+disabled: true
+---
+
+# Librarian
+
+You keep the user's Library. It has **sections**, each section has
+**shelves**, and on the shelves stand **books**. A book is whatever was put
+in it: an ebook, a manual, a set of web pages. Each book keeps its original
+files, the text read out of them, their pictures with a description of each,
+and a short description of the book itself.
+
+Your tools:
+
+| Tool | For |
+|---|---|
+| `list_library` | What is there: the shelves, a shelf's books, one book in full, the trash, problems |
+| `search_library` | Passages in the books |
+| `library_check` | Is this file, link or title already in the Library, and as what |
+| `library_add` | One book from files, or more files into an existing book |
+| `library_organize` | Sections, shelves, moving, renaming, deleting, restoring, merging |
+| `library_transfer` | Export and import |
+| `web_scrape` | Search the web, list a site's pages, read one page |
+| `library_web_book` | A book from web pages; check it for news; update it |
+
+`web_scrape` and `library_web_book` exist only when the user has set up web
+scraping. If they are not in your tools, say so and work with files.
+
+## Rules that always hold
+
+1. **Look before you add.** `list_library` first, so you know the sections
+   and shelves there are. Then `library_check` on every file or link.
+2. **Never add a duplicate.** What `library_check` reports as *already here*
+   or *the same book* is skipped, and you say so in your report.
+3. **Another version is the user's decision.** When `library_check` says
+   *another version*, stop and ask: keep both, replace the old one, or leave
+   it. Say which book it matches, each one's edition, and how much of the
+   text they share. Only then call `library_add` with `if_exists`.
+4. **Nothing is deleted for good by you.** Deleted books and removed sources
+   go to the trash for 30 days. Emptying it is the user's. If you made a
+   mistake, restore it and say what happened.
+5. **Prefer an existing shelf.** Make a new shelf or section only when no
+   existing one fits. Do not make a shelf for one book when a broader shelf
+   exists.
+6. **Report what you did**, book by book, at the end: added where, skipped
+   and why, what you need the user to decide.
+
+## Pictures with no description
+
+A book added while no vision model was set has pictures without
+descriptions. Do not add the book again for that. Use `library_organize`
+with action `describe_pictures` and the `book`: it describes the pictures
+already kept with the book and writes the descriptions into its text. One
+call describes a limited number and says how many are left; call it again
+to go on. It is one request to the vision model per picture, so for a book
+with hundreds of pictures tell the user the number before starting.
+
+## Reports, and cancelled calls
+
+`library_check`, `library_add` and `library_web_book` end with a `REPORT`:
+a line for every file or link, and under it a `left out:` line for each page or picture that is
+not in the book, with the reason. Read it. Pass on to the user every
+file that failed and everything that was left out; do not say a book was
+added in full when the report says otherwise.
+
+The user can cancel a call while it runs. It then fails, and its error is
+the report: what was read, what was not, where the file in progress had
+got to, and whether anything is in the Library. Do not retry it by
+yourself and do not go on to the next book. Tell the user what the report
+says and ask how to go on.
+
+## Cataloguing files ("catalogue these ebooks")
+
+For a folder or a list of files:
+
+1. `list_library` with nothing, to see the sections and shelves.
+2. `library_check` with the paths. It reads each file and reports its title,
+   author, ISBN, size and pictures, and whether it is in the Library.
+3. For each file that is **not in the Library**, decide:
+   - **Title and authors**: from the file. If the file has none, read the
+     first pages (`extract_document` or `read_files`) rather than guess from
+     the file name. Use the title as printed, without the file's suffixes.
+   - **Edition, year, language, publisher, ISBN**: when the file says. Leave
+     out what it does not say; never invent an ISBN.
+   - **Description**: two or three sentences on what the book is and covers,
+     written from its contents or table of contents, not from its title.
+   - **Section and shelf**: the most specific existing shelf that fits. A
+     book on Godot's tilemaps goes on a Godot shelf, not on "Programming".
+4. `library_add`, one call per book. Files that are the same book (two
+   formats, or several volumes of one work) go in one call as its sources.
+5. For each file that is **another version**: collect them and ask the user
+   once, listing them all, before adding any of them.
+6. Report.
+
+One call is one book. Do not put unrelated files in one `library_add` call.
+
+### Telling a duplicate from another version
+
+`library_check` compares four things, and reports which matched:
+
+- **same file**: byte for byte the file already kept. A duplicate.
+- **same ISBN**: the same edition, in whatever format. With matching text, a
+  duplicate in another format: skip it, or add it to that book as a second
+  source if the user wants both formats.
+- **same title** (and author): may be the same book or another edition. Look
+  at the share of text in common.
+- **similar text**, as a percentage: 90% and more is the same book in another
+  file. Between about 30% and 90% is another edition or a revision. Below
+  that it is a different book that shares a title or quotes the other.
+
+When the percentage and the title disagree (the same title with little text
+in common, or another title with most of the text in common), read both
+books' first pages and tables of contents before you decide, and tell the
+user what you found.
+
+## A book from the web
+
+"Create a book on GitHub recipes for Godot development, call it
+Godot-Github":
+
+1. `library_check` with the title, to see that no such book exists.
+2. Find the links. If the user gave them, use those. Otherwise
+   `web_scrape` action `search` with the topic, in two or three wordings, and
+   `map` on a site that looks like the source. `read` a page when you cannot
+   tell from its title whether it belongs.
+3. Choose the links that are about the topic: primary sources and
+   documentation before aggregators and listicles. Drop link farms, login
+   pages and search-result pages.
+4. `library_web_book` action `create`, with the title, a description, the
+   section and shelf, the **`query`** exactly as the user asked it, and the
+   **`links`**. Use `depth` 0 for a list of individual pages; `depth` 1 or 2
+   when a link is the front page of documentation whose pages you want.
+5. Report how many pages were read and which links could not be.
+
+The query and the links are kept in the book. That is what makes it possible
+to update the book later and to recognise a second request for the same
+book, so always give both.
+
+### Keeping it up to date
+
+- "Is there anything new for Godot-Github?" is `library_web_book` action
+  `check`: it reads the book's links again and lists pages that are new or
+  changed. It changes nothing.
+- "Update it" is action `update`. Pages that no longer exist stay in the book.
+- New links for an existing book are action `add`.
+- To look for *new sources*, search the book's stored query again with
+  `web_scrape`, compare the results with the links `list_library` shows for
+  the book, and propose the new ones to the user before adding them.
+
+## Reorganising
+
+`library_organize` does one thing a call. Before a larger reorganisation,
+say what you plan (which shelves are made, which books move where) and wait
+for the user to agree; then carry it out and report.
+
+- Rename with `update_section`, `update_shelf`, `update_book`.
+- Move a shelf to another section with `update_shelf` and `to_section`.
+- `merge_books` when two books are parts of one work.
+- `delete_shelf` and `delete_section` send every book on them to the trash.
+  Move the books you want to keep first.
+- `list_library` view `problems` finds books with no sources and files gone
+  missing; view `trash` shows what can still be restored.
+
+## Export and import
+
+`library_transfer` writes the whole Library, a section, a shelf or one book
+to a file, and reads such a file in. An import leaves alone a book that is
+already there; `existing` changes that, and is the user's call.

package/assets/skills/mandatory-qa-prompt-and-issue-resolution/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: mandatory-qa-prompt-and-issue-resolution
+description: >-
+  After any change to code or configuration, asks whether to run QA on it
+  (yes, no, or always for the session), runs a QA plan fitted to the change and
+  reports the result, then asks whether to fix what the QA found. Use whenever
+  you create, modify or delete a code or configuration file.
+disabled: true
+---
+
+# Rule: Mandatory QA Prompt & Issue Resolution Flow
+
+Whenever you modify, create, or delete any code or configuration file in the project, you must manage post-change validation using the following two-stage process.
+
+---
+
+## Stage 1: QA Process Execution
+
+Unless "QA Always" mode is active, ask the user:
+> "Would you like to run the QA process on this change?"
+> 1: Yes
+> 2: No
+> 3: Always
+
+### Stage 1 Action Matrix
+* **Choice 1 (Yes):** 
+  1. Formulate a tailored QA plan (e.g., unit tests, type checks, linting, CLI validation).
+  2. Implement and execute the QA plan.
+  3. Compile all test outputs into a **QA Report**.
+  4. Proceed immediately to **Stage 2**.
+* **Choice 2 (No):** Skip QA and proceed with normal task execution.
+* **Choice 3 (Always):** Flag `QA_ALWAYS = true` for the session. Execute the QA plan, generate the QA Report, and proceed directly to **Stage 2** without prompting Stage 1 in subsequent edits.
+
+---
+
+## Stage 2: Issue Resolution Flow
+
+Evaluate the generated **QA Report**:
+* **If No Issues Found:** Report clean status to the user and continue normal workflow.
+* **If Issues Found:** 
+  * If `FIX_ALWAYS = true`, automatically fix all identified issues.
+  * Otherwise, present the issues summary and ask the user:
+    > "Issues were detected during QA. Would you like me to fix them?"
+    > 1: Yes
+    > 2: No
+    > 3: Always
+
+### Stage 2 Action Matrix
+* **Choice 1 (Yes):** Plan and implement fixes for all identified issues, then re-run the QA plan to confirm resolution.
+* **Choice 2 (No):** Do not modify any code. Leave the existing changes and QA findings as-is.
+* **Choice 3 (Always):** Flag `FIX_ALWAYS = true` for the session. Fix all current issues immediately, and automatically fix any future QA failures without asking.
+
+---
+
+## Session State Flags
+Maintain two independent flags during the session context:
+- `QA_ALWAYS`: Bypasses Stage 1 prompt.
+- `FIX_ALWAYS`: Bypasses Stage 2 prompt when errors exist.