brickie-core 0.1.0__tar.gz

brickie_core-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
+      - run: just check

brickie_core-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    uses: ./.github/workflows/ci.yaml
+
+  publish:
+    needs: check
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write # create the GitHub Release
+      id-token: write # Trusted Publishing to PyPI
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
+      - run: just release::build "$GITHUB_REF_NAME"
+      - run: just release::publish
+      - run: just release::github "$GITHUB_REF_NAME"
+        env:
+          GH_TOKEN: ${{ github.token }}

brickie_core-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+.venv/
+__pycache__/
+.env
+CLAUDE.local.md
+/build/
+dist/

brickie_core-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: local
+    hooks:
+      - id: black
+        name: black
+        entry: uv run black --check src tests scripts
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: ruff
+        name: ruff
+        entry: uv run ruff check src tests scripts
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: ty
+        name: ty
+        entry: uv run ty check src tests scripts
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        always_run: true
+        pass_filenames: false

brickie_core-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

brickie_core-0.1.0/AGENTS.md

@@ -0,0 +1,77 @@
+# Working agreement
+
+Read before any work in this repo. These rules are non-negotiable.
+
+## Building issues
+
+- Build every issue test-first with `/tdd` (red → green → refactor) unless it has no testable behaviour (pure docs, config-only changes). Say so in the PR when skipping.
+- Work in tracer-bullet vertical slices: each issue lands an end-to-end path, not a layer.
+
+## Writing docs
+
+Every PR that changes what a user sees or does updates its docs pages in the same PR, and adds its line to `## Unreleased` in `docs/changelog.md`. A change that needs an edit to a user's project says what to change.
+
+### One job per page
+
+- **Get started** takes you down one path to a working result.
+- **A guide** does one task, and its title is that task: "Add a source".
+- **A concept page** explains how Brickie thinks about one idea, and why.
+- **Reference** is generated. Don't write it by hand.
+
+A page never mixes these. If a guide starts explaining an idea, link to the concept page.
+
+### Voice
+
+- Write to "you", in the present tense, in short sentences.
+- Say what happens. Not "Brickie allows you to quarantine rows" but "rows that fail go to quarantine".
+- No marketing words: no "powerful", "seamless", "simply", "easily".
+- Brickie's terms are lowercase in prose: a source, a gold model, quarantine, the platform contract. Identifiers stay in code: `keys`, `brickie.platform.yaml`, `BRK209`.
+
+### Show, then tell
+
+- Each guide step is a command or a file, followed by the real output it produces.
+- Write commands bare, `brickie validate`, for a reader whose project's `.venv` is active.
+- Examples come from Kettle, the fictional tea shop in `src/brickie/examples/kettle/`. A code block titled with a file path, ```` ```yaml title="domains/sales/sources/orders.yaml" ````, must match that file in Kettle. Reference pages use placeholders such as `<source>`.
+
+### Link, don't repeat
+
+- Each idea is explained on one page. Every other page links to it.
+- A guide ends with "Next steps".
+
+### Notes
+
+- Use notes rarely. `> **Note**` is for what would surprise a careful reader. `> **Warning**` is only for where data could be lost.
+- Use plain Markdown, so pages read the same on GitHub.
+
+## Design
+
+- Follow SOLID: small modules with one reason to change, depend on interfaces rather than concrete implementations where a seam is genuinely needed, and extend by adding code rather than editing stable code.
+- Readability beats abstraction. Code is read far more than it is written, so prefer the plain, obvious version. Don't add an interface, base class, factory or layer of indirection until there is a second concrete use or a test that needs the seam. Three similar lines are better than a premature abstraction.
+- A reader should be able to follow a module top to bottom without jumping through several files.
+
+## Python toolchain
+
+| Concern | Tool |
+| --- | --- |
+| Environments, dependencies, running | `uv` (`uv sync`, `uv run`, `uv add`); no pip, no manual venvs |
+| Formatting | `black` |
+| Linting | `ruff` (lint only; `black` owns formatting, so `ruff format` is not used) |
+| Type checking | `ty` |
+| Tests | `pytest`, run via `uv run` |
+| Gate | `pre-commit` runs all of the above; CI runs the same hooks |
+
+Nothing merges with a failing hook. Don't add `# noqa`, `# type: ignore` or skipped tests without a comment explaining why.
+
+Any additional code-quality tooling (coverage thresholds, dependency license checks, secret scanning, dependency auditing) is welcome and, once added, equally non-negotiable.
+
+## Task runner
+
+- `just` is the single entry point for every routine task; CI calls the same recipes.
+- Keep the root `justfile` lean: it holds only top-level recipes (`check`, `test`, `fmt`, `lint`, `typecheck`) and imports modules. Group the rest in modules under `just/` (e.g. `just/dev.just`, `just/release.just`, `just/databricks.just`) via `mod`, so each file stays short and readable.
+- A recipe that grows beyond a few lines becomes a script under `scripts/`, called from the recipe.
+
+## CI/CD
+
+- CI is a thin wrapper over `just`: workflow steps call recipes rather than inlining shell, so local runs and CI behave the same.
+- Where steps repeat across workflows, extract them into reusable components (reusable workflows via `workflow_call`, composite actions under `.github/actions/`) rather than copying them. Do this when there is real repetition, not speculatively; one workflow that reads top to bottom beats a maze of tiny pieces.
+- Pin third-party actions to a version or commit SHA.

brickie_core-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

brickie_core-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

brickie_core-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: brickie-core
+Version: 0.1.0
+Summary: Bring the software development lifecycle to Databricks pipelines
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: click>=8.3
+Requires-Dist: pydantic>=2.14.2
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: sqlglot==26.*
+Requires-Dist: typer>=0.27.3
+Description-Content-Type: text/markdown
+
+<h1 align=center><code>brickie</code></h1>
+
+<div align=center>
+  <a href=https://github.com/nimblestax/brickie-core/actions/workflows/ci.yaml>
+    <img src=https://github.com/nimblestax/brickie-core/actions/workflows/ci.yaml/badge.svg alt="build status">
+  </a>
+  <a href=LICENSE>
+    <img src=https://img.shields.io/badge/license-Apache%202.0-blue.svg alt="Apache 2.0 license">
+  </a>
+</div>
+<br>
+
+Brickie brings the software development lifecycle to Databricks. Today it covers pipelines, from bronze to gold: config-driven, reviewed in pull requests, tested, and promoted from dev to prod. It grows to cover more of the platform.
+
+**Status:** early development, and below 1.0, so a minor release may need edits to your project. Install it into your project with `uv add --dev brickie-core`. The Plan shown on [nimblestax.com](https://nimblestax.com) is illustrative: Brickie has no Plan command today.
+
+A pipeline is YAML and SQL in your repo. A Source says where data lands:
+
+```yaml
+# domains/sales/sources/orders.yaml
+kind: source
+version: 1
+path: /Volumes/{env}_sales/bronze/landing/orders
+format: json
+```
+
+A Model is the SQL you'd write anyway, using Logical Names:
+
+```sql
+-- domains/sales/models/fct_orders.sql
+SELECT order_id, amount
+FROM sales.silver.orders
+```
+
+Brickie compiles that for each Environment:
+
+```console
+$ brickie compile --env dev
+CREATE OR REFRESH STREAMING TABLE dev_sales.bronze.orders
+TBLPROPERTIES ('pipelines.reset.allowed' = 'false')
+AS SELECT *
+FROM STREAM read_files('/Volumes/dev_sales/bronze/landing/orders', format => 'json');
+...
+CREATE OR REFRESH MATERIALIZED VIEW dev_sales.gold.fct_orders AS
+SELECT order_id, amount
+FROM dev_sales.silver.orders
+```
+
+And it catches mistakes before anything touches a workspace:
+
+```console
+$ brickie validate
+BRK201 domains/sales/models/fct_orders.sql: sales.silver.ordrs isn't a table in this project.
+  Fix: Declare a Source or Gold Model with this name, or correct the Logical Name.
+```
+
+## What works today
+
+- `brickie init` creates a working project, with GitHub Actions workflows.
+- `brickie validate` checks config and SQL references with no workspace. A Model's dependencies come from its SQL, with no list to keep: CTEs, aliases and `STREAM(...)` just work, and anything Brickie can't read, such as `IDENTIFIER(...)`, is an error rather than a guess.
+- `brickie compile` writes generated code, or prints it for one Environment.
+- `brickie deploy` deploys to an Environment and refreshes its tables.
+- `brickie schema` prints any Kind's fields.
+- Every command has [`--json` output](docs/reference/json-output.md), rule IDs and fixed exit codes.
+
+## The Nimblestax Way
+
+Brickie is built around an opinionated way of building on Databricks. Read the principles at [nimblestax.com/way](https://nimblestax.com/way).
+
+## Follow progress
+
+Watch this repo's releases on GitHub.
+
+## License
+
+[Apache License 2.0](LICENSE). Contributions are accepted under the [Developer Certificate of Origin](https://developercertificate.org/): sign off each commit with `git commit -s`.

brickie_core-0.1.0/README.md

@@ -0,0 +1,76 @@
+<h1 align=center><code>brickie</code></h1>
+
+<div align=center>
+  <a href=https://github.com/nimblestax/brickie-core/actions/workflows/ci.yaml>
+    <img src=https://github.com/nimblestax/brickie-core/actions/workflows/ci.yaml/badge.svg alt="build status">
+  </a>
+  <a href=LICENSE>
+    <img src=https://img.shields.io/badge/license-Apache%202.0-blue.svg alt="Apache 2.0 license">
+  </a>
+</div>
+<br>
+
+Brickie brings the software development lifecycle to Databricks. Today it covers pipelines, from bronze to gold: config-driven, reviewed in pull requests, tested, and promoted from dev to prod. It grows to cover more of the platform.
+
+**Status:** early development, and below 1.0, so a minor release may need edits to your project. Install it into your project with `uv add --dev brickie-core`. The Plan shown on [nimblestax.com](https://nimblestax.com) is illustrative: Brickie has no Plan command today.
+
+A pipeline is YAML and SQL in your repo. A Source says where data lands:
+
+```yaml
+# domains/sales/sources/orders.yaml
+kind: source
+version: 1
+path: /Volumes/{env}_sales/bronze/landing/orders
+format: json
+```
+
+A Model is the SQL you'd write anyway, using Logical Names:
+
+```sql
+-- domains/sales/models/fct_orders.sql
+SELECT order_id, amount
+FROM sales.silver.orders
+```
+
+Brickie compiles that for each Environment:
+
+```console
+$ brickie compile --env dev
+CREATE OR REFRESH STREAMING TABLE dev_sales.bronze.orders
+TBLPROPERTIES ('pipelines.reset.allowed' = 'false')
+AS SELECT *
+FROM STREAM read_files('/Volumes/dev_sales/bronze/landing/orders', format => 'json');
+...
+CREATE OR REFRESH MATERIALIZED VIEW dev_sales.gold.fct_orders AS
+SELECT order_id, amount
+FROM dev_sales.silver.orders
+```
+
+And it catches mistakes before anything touches a workspace:
+
+```console
+$ brickie validate
+BRK201 domains/sales/models/fct_orders.sql: sales.silver.ordrs isn't a table in this project.
+  Fix: Declare a Source or Gold Model with this name, or correct the Logical Name.
+```
+
+## What works today
+
+- `brickie init` creates a working project, with GitHub Actions workflows.
+- `brickie validate` checks config and SQL references with no workspace. A Model's dependencies come from its SQL, with no list to keep: CTEs, aliases and `STREAM(...)` just work, and anything Brickie can't read, such as `IDENTIFIER(...)`, is an error rather than a guess.
+- `brickie compile` writes generated code, or prints it for one Environment.
+- `brickie deploy` deploys to an Environment and refreshes its tables.
+- `brickie schema` prints any Kind's fields.
+- Every command has [`--json` output](docs/reference/json-output.md), rule IDs and fixed exit codes.
+
+## The Nimblestax Way
+
+Brickie is built around an opinionated way of building on Databricks. Read the principles at [nimblestax.com/way](https://nimblestax.com/way).
+
+## Follow progress
+
+Watch this repo's releases on GitHub.
+
+## License
+
+[Apache License 2.0](LICENSE). Contributions are accepted under the [Developer Certificate of Origin](https://developercertificate.org/): sign off each commit with `git commit -s`.

brickie_core-0.1.0/docs/changelog.md

@@ -0,0 +1,40 @@
+---
+title: Changelog
+description: What changed in each release of Brickie, newest first.
+---
+
+Every release of Brickie, newest first. Each section is also that release's notes on GitHub.
+
+Each pull request that changes what you see adds its line under Unreleased, so each release's section is built up by its pull requests. A release renames Unreleased to its version.
+
+Brickie follows [Semantic Versioning](https://semver.org). Before 1.0, a minor release, such as 0.2.0, may change config or commands in ways that need edits to your project, and its section here says what to change. A patch release, such as 0.2.1, never does.
+
+## Unreleased
+
+## 0.1.0
+
+The first release. Install it into your project with `uv add --dev brickie-core`.
+
+- [`brickie init`](reference/commands/init.md) creates a project folder and asks where your tables live: `domain-catalogs` (`dev_sales.silver.orders`, the default), `layer-catalogs` (`dev_silver.sales.orders`) or `environment-catalogs` (`dev.sales_silver.orders`). `brickie.platform.yaml` keeps that choice as `naming.style`. See [Naming](concepts/naming.md).
+  - It refuses a folder that already holds `brickie.platform.yaml`, with [`BRK909`](reference/rules/brk909.md), and writes nothing.
+  - `--ci github` adds GitHub Actions workflows, `.github/workflows/brickie-pull-request.yaml` and `.github/workflows/brickie-merge.yaml`. They install `brickie-core` at the version `BRICKIE_SPEC` names.
+  - It lists the Volumes the project's sources read in dev, with the catalogs and schemas to create.
+  - `--example kettle` writes Kettle, the fictional tea shop every docs page draws its examples from, with two days of sample data and the commands that upload day 1.
+- Environments are named freely and carry a role: `role: development` on exactly one, and `role: production` on at most one. Any other environment is a stage. Commands that read default to the development environment, and an environment without a `host` uses its host. See [Environments](concepts/environments.md).
+- [`brickie validate`](reference/commands/validate.md) checks config and SQL with no workspace. A gold model's dependencies come from its SQL, and anything Brickie can't read, such as `IDENTIFIER(...)`, is an error rather than a guess.
+  - Tables are read in build order. A gold model reads silver, a gold model in its own domain, another domain's exported silver, or gold in the shared domain. See [Domains and layers](concepts/domains-and-layers.md).
+  - Model layers have no order, and a gold model's folder sets its layer. A loop of reads across model layers fails.
+  - `--platform` signs in to an environment's workspace and checks that the catalogs and schemas the project needs are there.
+  - It warns when a skill was written by another Brickie version.
+- [`brickie compile`](reference/commands/compile.md) writes the generated code, or prints it for one environment. A gold model that reads `STREAM(...)` compiles to a streaming table, and any other gold model to a materialized view. See [How Brickie reads a gold model's SQL](concepts/how-brickie-reads-a-gold-models-sql.md).
+- [`brickie deploy`](reference/commands/deploy.md) deploys to the environment `--env` names and refreshes its tables. When a refresh fails, it says why. See [Recover from a failed refresh](guides/recover-from-a-failed-refresh.md).
+  - Each environment has one Job, named for it, such as `kettle_dev_refresh`. It waits only where one pipeline reads another's tables, so a failed pipeline skips only what reads from it.
+  - An environment can refresh on a schedule. A schedule runs in the production environment and is paused elsewhere. See [Schedule refreshes](guides/schedule-refreshes.md).
+- [`brickie schema`](reference/commands/schema.md) prints any Kind's fields.
+- A source lands in bronze, and silver either appends it or upserts it by `keys` and `sequence_by`, with Type 1 or Type 2 history and `delete_when` for deletes.
+- Seeds load small reference tables from CSV files in the repo.
+- Expectations check silver rows, and rows that fail are kept in quarantine. See [Expectations](concepts/expectations.md).
+- Brickie brings its own Databricks CLI, version 1.23.0, and never runs the `databricks` on your PATH. [`brickie databricks`](reference/commands/databricks.md) runs it, and `BRICKIE_DATABRICKS_CLI` points Brickie at one you installed yourself. See [The Databricks CLI](concepts/the-databricks-cli.md).
+- `brickie init` writes Brickie skills for coding agents, `brickie-add-source` and `brickie-add-model`, into `.agents/skills/` and `.claude/skills/`. [`brickie skills update`](reference/commands/skills.md#update) refreshes them. See [Brickie skills](concepts/brickie-skills.md).
+- Every command but `brickie databricks` has `--json` output, with Rule IDs and fixed exit codes. See [JSON output](reference/json-output.md).
+- Every Rule has its own reference page, listed in the [Rules index](reference/rules/index.md).

brickie_core-0.1.0/docs/concepts/brickie-skills.md

@@ -0,0 +1,56 @@
+---
+title: Brickie skills
+description: The agent skills brickie init writes into your repo, why there are two copies, and how they stay in step with Brickie.
+---
+
+A Brickie skill guides a coding agent through one task with Brickie's commands, such as adding a source. `brickie init` writes them into your project, and you commit them like any other file.
+
+```console
+$ brickie init kettle
+...
+Wrote Brickie Skills for coding agents:
+  .agents/skills/brickie-add-model
+  .claude/skills/brickie-add-model
+  .agents/skills/brickie-add-source
+  .claude/skills/brickie-add-source
+```
+
+Each skill is one `SKILL.md` that names the commands to run. It doesn't list a kind's fields. It tells the agent to run `brickie schema <kind>`, so the fields come from the Brickie you have installed. No skill deploys: an agent writes the change, and a person promotes it.
+
+## Where they go
+
+Skills follow the [Agent Skills](https://agentskills.io) standard and use only its fields, so every agent that reads the standard gets the same steps.
+
+`.agents/skills/` holds the main copy, in the folder many coding agents share. Claude Code reads only `.claude/skills/`, so it gets an identical copy. They are copies, not symlinks, because symlinks don't check out reliably on Windows.
+
+Brickie only ever adds `brickie-*` folders. Your own skills, settings and other files in `.agents/` and `.claude/` stay as they are, and a `brickie-*` folder that already exists is left alone. If Git ignores either folder, `brickie init` warns with [`BRK914`](../reference/rules/brk914.md), because skills that aren't committed stay on one machine.
+
+To write no skills, run `brickie init --skills none`. `brickie skills update` writes them later if you change your mind.
+
+## Keeping them in step
+
+Each skill records the Brickie version that wrote it, in its front matter:
+
+```yaml
+metadata:
+  brickie-version: "0.1.0"
+  brickie-digest: "..."
+```
+
+After you upgrade Brickie, `brickie validate` warns with [`BRK129`](../reference/rules/brk129.md) for each skill an older version wrote, because its steps can name commands that have changed. A warning doesn't fail validation.
+
+`brickie skills update` rewrites both copies of each skill to the installed version:
+
+```console
+$ brickie skills update
+Updated these Brickie Skills. Commit them:
+  .agents/skills/brickie-add-source
+  .claude/skills/brickie-add-source
+```
+
+`brickie-digest` records the text Brickie wrote, so `brickie skills update` can tell your edit from an older Brickie's text. If you edited a skill, it writes nothing, reports [`BRK915`](../reference/rules/brk915.md) and shows the difference. Move your steps into a skill of your own, outside the `brickie-*` folders, or run `brickie skills update --force` to replace them.
+
+## Next steps
+
+- [`brickie skills update`](../reference/commands/skills.md#update) lists its options and its JSON result.
+- [`brickie init`](../reference/commands/init.md) lists `--skills` with its other options.