duckpad 0.1.0__tar.gz

duckpad-0.1.0/.agents/skills/repository-conventions/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: repository-conventions
+description: Apply this repository's English writing rules, UI translation exception, and Conventional Commits rules whenever creating or editing files, reviewing changes, or preparing commit messages.
+---
+
+# Repository Conventions
+
+## Write repository content in English
+
+- Write all new or modified repository content in English, even when the user
+  gives instructions in French, except for the UI translation resources below.
+- Use English for documentation, comments, identifiers, file names, test names,
+  example text, default user-facing strings, log messages, and error messages.
+- Allow French only in localized UI values stored in dedicated translation
+  resource files, including translations of user-facing error messages. Keep
+  translation keys, file names, and comments in English. Use translation keys
+  from application code instead of embedding French strings there.
+- Translate French wording into English before adding it elsewhere in the
+  repository.
+- Keep conversational replies in the user's preferred language.
+
+## Use Conventional Commits
+
+Every commit message must follow this structure:
+
+```text
+<type>[optional scope][optional !]: <English summary>
+
+[optional English body]
+
+[optional footers]
+```
+
+- Use a lowercase type that describes the change: `feat`, `fix`, `docs`, `style`,
+  `refactor`, `perf`, `test`, `build`, `ci`, `chore`, or `revert`.
+- Add a short English scope when it helps identify the affected component.
+- Write a concise English summary in the imperative, such as `add`, `fix`, or
+  `update`. Keep body text and footer descriptions in English as well.
+- Mark breaking changes with `!` before the colon or a
+  `BREAKING CHANGE: <English explanation>` footer.
+- Apply the same format to merge, squash, revert, and amended commit messages;
+  replace generated messages when necessary.
+
+Examples:
+
+```text
+docs(agents): add repository conventions
+fix(editor): preserve selection when saving
+feat(api)!: require authentication for note updates
+```
+
+Before finishing a change, verify that any French text is limited to localized
+UI values in dedicated translation resources, and check any proposed commit
+message against the format above.

duckpad-0.1.0/.dockerignore

@@ -0,0 +1,20 @@
+.git
+.agents
+.multica
+.venv
+.duckpad-dev
+.env
+.env.*
+**/__pycache__
+**/node_modules
+**/*.tsbuildinfo
+.pytest_cache
+.ruff_cache
+dist
+src/duckpad/static
+test-results
+playwright-report
+frontend/test-results
+frontend/playwright-report
+docs
+tests

duckpad-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: Validate Duckpad
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  acceptance:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.11', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --extra dev --locked
+      - run: uv run ruff check src tests scripts
+      - run: uv run ruff format --check src tests scripts
+      - run: uv run pytest -q
+      - run: npm ci --prefix frontend
+      - run: npm run build --prefix frontend
+      - run: npm exec --prefix frontend -- playwright install --with-deps chromium
+      - run: npm run test:e2e --prefix frontend
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: browser-diagnostics-${{ matrix.python }}
+          path: frontend/test-results/

duckpad-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,119 @@
+name: Release Duckpad
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Validate and build release
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      prerelease: ${{ steps.release.outputs.prerelease }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --extra dev --locked
+      - name: Validate tag and generate release notes
+        id: release
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+          RELEASE_REPOSITORY: ${{ github.repository }}
+        run: uv run python scripts/release.py "$RELEASE_TAG" --repository "$RELEASE_REPOSITORY" --output release-notes.md
+      - run: uv run ruff check src tests scripts
+      - run: uv run ruff format --check src tests scripts
+      - run: uv run pytest -q
+      - run: npm ci --prefix frontend
+      - run: npm run build --prefix frontend
+      - run: npm exec --prefix frontend -- playwright install --with-deps chromium
+      - run: npm run test:e2e --prefix frontend
+      # uv builds the wheel from the sdist, checking that the source archive is complete.
+      - run: uv build
+      - run: uv tool run --from twine==7.0.0 twine check --strict dist/*
+      - name: Smoke test the installed wheel outside the checkout
+        run: |
+          uv venv /tmp/duckpad-release-smoke
+          uv pip install --python /tmp/duckpad-release-smoke/bin/python dist/*.whl
+          uv run python scripts/smoke_wheel.py --python /tmp/duckpad-release-smoke/bin/python
+      - name: Calculate distribution checksums
+        working-directory: dist
+        run: sha256sum *.whl *.tar.gz > SHA256SUMS
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-bundle
+          path: |
+            dist/
+            release-notes.md
+          if-no-files-found: error
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: release-browser-diagnostics
+          path: frontend/test-results/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/duckpad/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: release-bundle
+      - name: Verify and stage distributions
+        run: |
+          (cd dist && sha256sum --check SHA256SUMS)
+          mkdir packages
+          cp dist/*.whl dist/*.tar.gz packages/
+      - name: Publish with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+        with:
+          packages-dir: packages/
+
+  publish-github:
+    name: Publish GitHub release
+    needs: [build, publish-pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: release-bundle
+      - name: Publish notes and the exact PyPI artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ github.ref_name }}
+          PRERELEASE: ${{ needs.build.outputs.prerelease }}
+        run: |
+          (cd dist && sha256sum --check SHA256SUMS)
+          flags=()
+          if [[ "$PRERELEASE" == true ]]; then
+            flags+=(--prerelease --latest=false)
+          fi
+          gh release create "$RELEASE_TAG" dist/*.whl dist/*.tar.gz dist/SHA256SUMS \
+            --verify-tag --title "Duckpad $RELEASE_TAG" --notes-file release-notes.md "${flags[@]}"

duckpad-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+node_modules/
+dist/
+src/duckpad/static/
+.duckpad-dev/
+test-results/
+playwright-report/
+*.egg-info/
+.coverage
+release-notes.md
+*.tsbuildinfo
+.multica/
+.env
+.env.*
+!.env.example

duckpad-0.1.0/AGENTS.md

@@ -0,0 +1,24 @@
+# Repository Instructions
+
+Before modifying files or preparing commits in this repository, read and follow
+[the repository-conventions skill](.agents/skills/repository-conventions/SKILL.md).
+Apply it to every change, even when it is not explicitly invoked.
+
+- Write repository content in English, except localized UI values in dedicated
+  translation resource files, where French is allowed. Keep translation keys,
+  file names, code, comments, and documentation in English.
+- Use Conventional Commits for every commit message, written in English.
+
+## Multica development
+
+Follow [the Multica workflow](docs/MULTICA.md) for issues handled through Multica.
+Use a dedicated branch and pull request for every issue, deploy and verify its
+preview, then wait for the designated human reviewer's explicit approval before merging into `main` and
+publishing the merge to GitHub. Never interpret ticket creation or a successful
+check as merge approval. Use `bash scripts/preview.sh` for Duckpad previews.
+
+Keep private infrastructure details outside this public repository. Never include
+personal domains, preview URLs, server names, deployment identifiers, or credentials
+in tracked files, commits, GitHub pull requests, or public build output. Share
+preview URLs only in the private Multica issue; retrieve deployment configuration
+from the operator's private environment. Do not include credentials in tickets.

duckpad-0.1.0/Dockerfile

@@ -0,0 +1,33 @@
+FROM node:22-bookworm-slim AS frontend
+WORKDIR /build/frontend
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build
+
+# Prepared once on the preview server by scripts/provision-runtime.sh.
+FROM duckpad-python:3.12-duckdb2.0.0 AS backend
+WORKDIR /app
+ENV UV_LINK_MODE=copy UV_PYTHON_DOWNLOADS=never
+COPY pyproject.toml uv.lock README.md LICENSE .gitignore ./
+RUN uv sync --locked --no-dev --no-install-project --no-build-package duckdb \
+    && .venv/bin/python -c "import duckdb; assert duckdb.__version__ == '2.0.0'"
+COPY scripts/build_hook.py scripts/build_hook.py
+COPY src/ src/
+COPY --from=frontend /build/src/duckpad/static/ src/duckpad/static/
+RUN uv sync --locked --no-dev --no-editable --no-build-package duckdb
+
+FROM python:3.12-slim-bookworm AS runtime
+RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates libstdc++6 \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd --gid 10001 duckpad \
+    && useradd --uid 10001 --gid duckpad --home-dir /data --create-home duckpad
+WORKDIR /app
+COPY --from=backend /app/.venv/ /app/.venv/
+# Public previews use HTTPS even though the private proxy hop uses HTTP.
+ENV PATH="/app/.venv/bin:$PATH" PYTHONUNBUFFERED=1 DUCKPAD_SECURE_COOKIES=1
+USER duckpad
+EXPOSE 8765
+HEALTHCHECK --interval=15s --timeout=5s --start-period=20s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8765/', timeout=4)"
+CMD ["duckpad", "start", "--home", "/data/duckpad", "--host", "0.0.0.0", "--port", "8765", "--no-browser"]

duckpad-0.1.0/Dockerfile.duckdb

@@ -0,0 +1,13 @@
+# Build context: the validated wheel directory, not the repository root.
+FROM python:3.12-slim-bookworm
+# Coolify's cleanup skips tagged images carrying this label.
+LABEL coolify.managed="true" org.opencontainers.image.title="Duckpad portable DuckDB 2.0 runtime"
+COPY --from=ghcr.io/astral-sh/uv:0.9.5 /uv /usr/local/bin/uv
+RUN apt-get update && apt-get install -y --no-install-recommends libstdc++6 \
+    && rm -rf /var/lib/apt/lists/*
+COPY *.whl /tmp/duckdb-wheels/
+RUN uv venv /app/.venv \
+    && uv pip install --python /app/.venv/bin/python --no-index \
+       --find-links /tmp/duckdb-wheels duckdb==2.0.0 \
+    && /app/.venv/bin/python -c "import duckdb; assert duckdb.__version__ == '2.0.0'; assert duckdb.sql('select 42').fetchall() == [(42,)]" \
+    && rm -rf /tmp/duckdb-wheels

duckpad-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugues
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

duckpad-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: duckpad
+Version: 0.1.0
+Summary: A local SQL canvas with reproducible execution and cell lineage
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: duckdb>=2.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: filelock>=3.18
+Requires-Dist: psutil>=7.2
+Requires-Dist: pydantic>=2.10
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: sqlglot>=27
+Requires-Dist: uvicorn>=0.34
+Provides-Extra: dev
+Requires-Dist: apscheduler<4,>=3.11; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: git-cliff==2.14.2; extra == 'dev'
+Requires-Dist: httpx>=0.28; extra == 'dev'
+Requires-Dist: huey>=2.5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Requires-Dist: sqlalchemy>=2; extra == 'dev'
+Provides-Extra: integration
+Requires-Dist: boto3>=1.38; extra == 'integration'
+Requires-Dist: moto[server]>=5; extra == 'integration'
+Requires-Dist: oracledb>=3; extra == 'integration'
+Description-Content-Type: text/markdown
+
+# Duckpad
+
+Build local DuckDB pipelines on a visual canvas, inspect their results, and explain individual values back to their source cells. Duckpad combines a React/TypeScript interface with a Python/FastAPI execution service.
+
+## Start
+
+Requires **Python 3.11+ and Git** on `PATH`. Release wheels include the frontend, Monaco and its workers; Node.js is not needed to run the installed application.
+
+```sh
+pip install ./dist/duckpad-0.1.0-py3-none-any.whl
+duckpad start
+```
+
+The distribution is named `duckpad`. Version tags publish the package to PyPI and create a GitHub release with Conventional Commit notes and downloadable distributions. After the first release, install it with `pip install duckpad`. See the [release guide](docs/RELEASING.md) for one-time publishing setup and tagging instructions.
+
+Open the localhost address printed in the terminal. Sign in as `admin` using the password printed **once** on the first launch. The same password remains valid after a restart. The default instance directory is `$XDG_DATA_HOME/duckpad`, or `~/.local/share/duckpad`. Authentication, connection settings and execution history are kept there, outside project repositories.
+
+```sh
+duckpad start --home /path/to/my-instance --port 8765 --no-browser
+```
+
+Only one backend may own an instance directory at a time. Use separate `--home` directories for independent instances. The default address is `127.0.0.1`.
+
+## Try the complete example
+
+Choose **Open example project** and **Run pipeline**. The Northstar example creates CSV and Parquet inputs, joins customers to orders, computes ordered outputs, uses nested reusable components twice with separate parameters, computes aggregates, distinct counts, set operations and window ranks, and exports two CSV reports. Its `dev` and `prod` data are deliberately different.
+
+Select **Regional revenue**, choose the `report` output, then click a revenue cell. Follow a contribution into the nested aggregate and page through its source amounts. No external accounts are required for this example. See the [example tour](docs/EXAMPLE.md).
+
+![Northstar pipeline and preview](docs/images/workspace.png)
+
+## Included workflows
+
+- Drag templates onto the canvas, connect ports, configure typed parameters, and edit shared SQL definitions in Monaco.
+- Use guided filter, join-key and aggregate forms, or edit their generated SQL expressions.
+- Preview, filter and sort results; explain valid cells with five contributions per page and complete counts.
+- Group nodes into nested components, expose parameters, and import independent copies between projects.
+- Save automatically to Git, inspect diffs, open isolated branches or historical revisions, and explicitly merge changes.
+- Detect concurrent UI/file edits and resolve recoverable conflicts without losing either proposal.
+- Recompute manually, stop active SQL, retain stale previews after failure, and inspect durable execution history.
+- Configure reusable connections and environments outside project Git, with local, S3 and Oracle presets.
+- Switch English/French and light/dark themes without changing the project.
+- Monitor Duckpad server CPU and RAM as percentages with subtle background bars;
+  click for two minutes of history and RAM used / total in MiB or GiB. Samples
+  refresh every two seconds while the workspace is open; history resets on reload
+  or sign-out. Process memory comes from [psutil](https://psutil.io/platform/),
+  supporting Linux, macOS, and Windows. CPU includes all server threads, normalized
+  to the available CPU capacity (100% means fully used); RAM is current resident
+  memory divided by total capacity. CPU affinity and visible Linux cgroup v1/v2
+  limits constrain those capacities; otherwise system totals apply. Measurements
+  cover the Duckpad server process. Missing measurements are shown as unavailable.
+
+Language defaults to the first supported language in your browser preferences
+(English or French, with English as the fallback), and the theme defaults to your
+system color scheme. Manual choices are saved in this browser and take priority
+on subsequent visits.
+
+Results live in memory per worktree and environment. After a backend restart, history remains available but previews and lineage require another manual run. Editing or changing an external source does not launch a run automatically.
+
+## Develop and verify
+
+```sh
+bash scripts/setup.sh
+uv run duckpad start --home .duckpad-dev --no-browser
+```
+
+For frontend development, `npm run dev --prefix frontend` proxies `/api` to the backend on port 8765.
+
+```sh
+uv run ruff check src tests scripts
+uv run ruff format --check src tests scripts
+uv run pytest -q
+npm run check --prefix frontend
+npm exec --prefix frontend -- playwright install chromium
+npm run build --prefix frontend
+npm run test:e2e --prefix frontend
+uv build
+```
+
+The Playwright suite starts a disposable instance on port 8766. `DUCKPAD_CHROMIUM_EXECUTABLE` can point to an already installed Chromium executable. Building a release without compiled assets fails with an actionable message; editable installation permits building them afterward.
+
+## Documentation
+
+- [Release automation and publishing](docs/RELEASING.md)
+- [Multica issue workflow and preview deployment](docs/MULTICA.md)
+- [Architecture and execution invariants](docs/ARCHITECTURE.md)
+- [Project files, templates and components](docs/AUTHORING.md)
+- [Lineage coverage and limitations](docs/LINEAGE.md)
+- [Connector setup and validated compatibility](docs/CONNECTORS.md)
+- [Execution-service prototype and scheduling decision](docs/EXECUTION_SERVICE.md)
+- [Validation results and performance reference](docs/VALIDATION.md)
+
+The required dependency is `duckdb>=2.0`; the recorded validation uses **DuckDB 2.0.0 on Linux x86_64**. Oracle needs a matching OraDuck extension and Oracle Instant Client. S3 validation uses a local S3 emulator; live AWS IAM, TLS and deployment-specific behavior need their own integration checks. Details and reproducible commands are in the connector guide.

duckpad-0.1.0/README.md

@@ -0,0 +1,93 @@
+# Duckpad
+
+Build local DuckDB pipelines on a visual canvas, inspect their results, and explain individual values back to their source cells. Duckpad combines a React/TypeScript interface with a Python/FastAPI execution service.
+
+## Start
+
+Requires **Python 3.11+ and Git** on `PATH`. Release wheels include the frontend, Monaco and its workers; Node.js is not needed to run the installed application.
+
+```sh
+pip install ./dist/duckpad-0.1.0-py3-none-any.whl
+duckpad start
+```
+
+The distribution is named `duckpad`. Version tags publish the package to PyPI and create a GitHub release with Conventional Commit notes and downloadable distributions. After the first release, install it with `pip install duckpad`. See the [release guide](docs/RELEASING.md) for one-time publishing setup and tagging instructions.
+
+Open the localhost address printed in the terminal. Sign in as `admin` using the password printed **once** on the first launch. The same password remains valid after a restart. The default instance directory is `$XDG_DATA_HOME/duckpad`, or `~/.local/share/duckpad`. Authentication, connection settings and execution history are kept there, outside project repositories.
+
+```sh
+duckpad start --home /path/to/my-instance --port 8765 --no-browser
+```
+
+Only one backend may own an instance directory at a time. Use separate `--home` directories for independent instances. The default address is `127.0.0.1`.
+
+## Try the complete example
+
+Choose **Open example project** and **Run pipeline**. The Northstar example creates CSV and Parquet inputs, joins customers to orders, computes ordered outputs, uses nested reusable components twice with separate parameters, computes aggregates, distinct counts, set operations and window ranks, and exports two CSV reports. Its `dev` and `prod` data are deliberately different.
+
+Select **Regional revenue**, choose the `report` output, then click a revenue cell. Follow a contribution into the nested aggregate and page through its source amounts. No external accounts are required for this example. See the [example tour](docs/EXAMPLE.md).
+
+![Northstar pipeline and preview](docs/images/workspace.png)
+
+## Included workflows
+
+- Drag templates onto the canvas, connect ports, configure typed parameters, and edit shared SQL definitions in Monaco.
+- Use guided filter, join-key and aggregate forms, or edit their generated SQL expressions.
+- Preview, filter and sort results; explain valid cells with five contributions per page and complete counts.
+- Group nodes into nested components, expose parameters, and import independent copies between projects.
+- Save automatically to Git, inspect diffs, open isolated branches or historical revisions, and explicitly merge changes.
+- Detect concurrent UI/file edits and resolve recoverable conflicts without losing either proposal.
+- Recompute manually, stop active SQL, retain stale previews after failure, and inspect durable execution history.
+- Configure reusable connections and environments outside project Git, with local, S3 and Oracle presets.
+- Switch English/French and light/dark themes without changing the project.
+- Monitor Duckpad server CPU and RAM as percentages with subtle background bars;
+  click for two minutes of history and RAM used / total in MiB or GiB. Samples
+  refresh every two seconds while the workspace is open; history resets on reload
+  or sign-out. Process memory comes from [psutil](https://psutil.io/platform/),
+  supporting Linux, macOS, and Windows. CPU includes all server threads, normalized
+  to the available CPU capacity (100% means fully used); RAM is current resident
+  memory divided by total capacity. CPU affinity and visible Linux cgroup v1/v2
+  limits constrain those capacities; otherwise system totals apply. Measurements
+  cover the Duckpad server process. Missing measurements are shown as unavailable.
+
+Language defaults to the first supported language in your browser preferences
+(English or French, with English as the fallback), and the theme defaults to your
+system color scheme. Manual choices are saved in this browser and take priority
+on subsequent visits.
+
+Results live in memory per worktree and environment. After a backend restart, history remains available but previews and lineage require another manual run. Editing or changing an external source does not launch a run automatically.
+
+## Develop and verify
+
+```sh
+bash scripts/setup.sh
+uv run duckpad start --home .duckpad-dev --no-browser
+```
+
+For frontend development, `npm run dev --prefix frontend` proxies `/api` to the backend on port 8765.
+
+```sh
+uv run ruff check src tests scripts
+uv run ruff format --check src tests scripts
+uv run pytest -q
+npm run check --prefix frontend
+npm exec --prefix frontend -- playwright install chromium
+npm run build --prefix frontend
+npm run test:e2e --prefix frontend
+uv build
+```
+
+The Playwright suite starts a disposable instance on port 8766. `DUCKPAD_CHROMIUM_EXECUTABLE` can point to an already installed Chromium executable. Building a release without compiled assets fails with an actionable message; editable installation permits building them afterward.
+
+## Documentation
+
+- [Release automation and publishing](docs/RELEASING.md)
+- [Multica issue workflow and preview deployment](docs/MULTICA.md)
+- [Architecture and execution invariants](docs/ARCHITECTURE.md)
+- [Project files, templates and components](docs/AUTHORING.md)
+- [Lineage coverage and limitations](docs/LINEAGE.md)
+- [Connector setup and validated compatibility](docs/CONNECTORS.md)
+- [Execution-service prototype and scheduling decision](docs/EXECUTION_SERVICE.md)
+- [Validation results and performance reference](docs/VALIDATION.md)
+
+The required dependency is `duckdb>=2.0`; the recorded validation uses **DuckDB 2.0.0 on Linux x86_64**. Oracle needs a matching OraDuck extension and Oracle Instant Client. S3 validation uses a local S3 emulator; live AWS IAM, TLS and deployment-specific behavior need their own integration checks. Details and reproducible commands are in the connector guide.