cassis-cli 1.0.0__tar.gz → 1.1.1__tar.gz

cassis_cli-1.1.1/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 2026 Polymorph SAS
+
+   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.

cassis_cli-1.1.1/NOTICE

@@ -0,0 +1,4 @@
+Cassis CLI
+Copyright 2026 Polymorph SAS
+
+This product includes software developed at Polymorph SAS (https://getcassis.com).

cassis_cli-1.0.0/README.md → cassis_cli-1.1.1/PKG-INFO

@@ -1,3 +1,25 @@
+Metadata-Version: 2.4
+Name: cassis-cli
+Version: 1.1.1
+Summary: Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: cassis,ontology,ci,text-to-sql
+Author: Cassis
+Author-email: tech.admin@getcassis.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database
+Requires-Dist: httpx (>=0.24,<1.0)
+Requires-Dist: typer (>=0.12,<1.0)
+Project-URL: Documentation, https://github.com/GetCassis/cassis-cli#readme
+Project-URL: Homepage, https://getcassis.com
+Project-URL: Repository, https://github.com/GetCassis/cassis-cli
+Description-Content-Type: text/markdown
+
 # Cassis CLI
 
 Run Cassis actions from your CI pipelines:
@@ -5,8 +27,8 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology check` validates the ontology files in your repository with the exact same checks as the Cassis GitHub PR check (YAML parsing, round-trip, import validation) — so you can gate merges in any CI system, not just GitHub.
 - `cassis ontology fmt` rewrites the ontology files in canonical form (think `black`/`gofmt` for the ontology), so hand or agent edits pass the round-trip check.
 - `cassis ontology upload` uploads the ontology files to a Cassis project (full replace) and, by default, publishes them immediately as a new version — so a merge to your main branch can go live in one CI step.
-- `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local YAML files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
-- `cassis ontology pull` and `cassis ontology fmt` also write `<base-path>/AGENTS.md`, the Cassis ontology modeling guide, into the checkout (default `cassis/AGENTS.md`) — a managed file (generated banner; the CLI overwrites local edits) so a repo-aware coding agent loads current Cassis modeling doctrine by convention. It sits inside the ontology directory but is not part of the ontology tree (the CLI reads only `*.yml`/`*.yaml`), so it is never uploaded, validated, or pruned. Commit it alongside your ontology changes. The guide text ships inside the CLI package, so its version tracks the **installed cassis-cli version** — upgrade the CLI (`pip install -U cassis-cli`) and re-run `fmt` to pick up doctrine updates; an unpinned `pip install cassis-cli` in CI gets them automatically. The banner stamps a doctrine version, and the CLI never *downgrades* the file: if the checkout's `AGENTS.md` was written by a newer doctrine (a newer CLI, or Cassis itself on a publish), `fmt`/`pull` leave it in place, print an upgrade notice, and `fmt --check` still passes.
+- `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
+- `cassis ontology pull` and `cassis ontology fmt` also write `<base-path>/AGENTS.md`, the Cassis ontology modeling guide, into the checkout (default `cassis/AGENTS.md`) — a managed file (generated banner; the CLI overwrites local edits) so a repo-aware coding agent loads current Cassis modeling doctrine by convention. It sits inside the ontology directory but is not part of the ontology tree (which is the YAML files plus the domain Markdown files `domains/**/README.md`), so it is never uploaded, validated, or pruned. Commit it alongside your ontology changes. The guide text ships inside the CLI package, so its version tracks the **installed cassis-cli version** — upgrade the CLI (`pip install -U cassis-cli`) and re-run `fmt` to pick up doctrine updates; an unpinned `pip install cassis-cli` in CI gets them automatically. The banner stamps a doctrine version, and the CLI never *downgrades* the file: if the checkout's `AGENTS.md` was written by a newer doctrine (a newer CLI, or Cassis itself on a publish), `fmt`/`pull` leave it in place, print an upgrade notice, and `fmt --check` still passes.
 - The CLI identifies itself to the API (`User-Agent: cassis-cli/<version>`), and successful API responses advertise the newest published version — when you are behind, commands print a one-line upgrade notice on stderr (purely informational; output and exit codes are unchanged).
 - `cassis eval run` runs the project's eval suite against your local ontology files (scored in-memory — nothing is pushed to Cassis) and prints per-question results, so you can test the changes on your git branch before merging.
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
@@ -18,11 +40,21 @@ Run Cassis actions from your CI pipelines:
 pip install cassis-cli
 ```
 
+## Ontology file format
+
+The ontology tree under `<base-path>` (default `cassis/`) is:
+
+- **Project identity** — `project.yml`: the Cassis project id and format version. Written by `pull` and by server-side publish (the contexts that know the id); a local `fmt` won't create it.
+- **Domains** — Markdown files: every domain is the `README.md` of its folder — `domains/README.md` for the root, `domains/<path>/README.md` for each sub-domain. Each has a small YAML frontmatter block (`type`, `title`, `description`) and a Markdown body carrying the domain's `context_md`; a generated section at the bottom links the domain's tables and metrics (kept current by `fmt`/`pull` — edit your prose above it, and the PR check fails if the links are stale, so re-run `fmt`). The layout is a Cassis profile inspired by [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf): the files render on GitHub and read in any Markdown editor, but Cassis validates them strictly (unknown keys are flagged, not preserved).
+- **Tables, joins, metrics** — YAML, unchanged: `tables/<schema>/<table>.yml`, `joins.yml`, `metrics/<name>.yml`.
+
+**Migrating an existing repo** (domains were YAML `_project.yml` / `_domain.yml` before cassis-cli 1.1.0): upgrade and run `cassis ontology fmt` (or `cassis ontology pull` if you have no local edits) — it rewrites the domain files to Markdown and removes the old ones. Review the diff and commit. Cassis reads the old YAML domain files too, so an un-migrated repo keeps working until you convert it. **Uploading requires cassis-cli ≥ 1.1.0** — the server rejects an older CLI (which would drop the Markdown domain files) with a clear upgrade error.
+
 ## Setup
 
 1. Create an API key in Cassis under **Organization settings → API keys** (keys start with `sk-k6-`).
 2. Store it as a CI secret and expose it as `CASSIS_API_KEY`.
-3. For `pull`, `upload` and `eval run`: find the project ID (UUID) in the project's URL and expose it as `CASSIS_PROJECT_ID` (or pass `--project`).
+3. For `pull`, `upload`, `eval run`, `ontology test`, and `eval add-case`: the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID in the project's URL).
 
 ## Usage
 
@@ -112,7 +144,7 @@ cassis ontology fmt --check
 | 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another run already active, out of credits, or `--timeout` reached |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
-2000 YAML files / 5 MB total — far above real ontologies (a few hundred small
+2000 ontology files / 5 MB total — far above real ontologies (a few hundred small
 files). Beyond that the CLI fails fast with exit 2 before uploading anything;
 double-check `--base-path` if you hit it.
 
@@ -201,3 +233,19 @@ ontology-publish:
     CASSIS_API_KEY: $CASSIS_API_KEY
     CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID
 ```
+
+## About this repository
+
+[github.com/GetCassis/cassis-cli](https://github.com/GetCassis/cassis-cli) is a
+read-only mirror, synced automatically from the Cassis monorepo where the CLI is
+developed. Issues are welcome and watched; pull requests can't be merged here, so
+open an issue (or mail tech.admin@getcassis.com) and we'll port the patch upstream
+with credit.
+
+Only the CLI is open source. The Cassis backend it talks to is proprietary and
+requires an account.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
+

cassis_cli-1.0.0/PKG-INFO → cassis_cli-1.1.1/README.md

@@ -1,23 +1,3 @@
-Metadata-Version: 2.4
-Name: cassis-cli
-Version: 1.0.0
-Summary: Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines
-License: Proprietary
-Keywords: cassis,ontology,ci,text-to-sql
-Author: Cassis
-Author-email: tech.admin@getcassis.com
-Requires-Python: >=3.10,<4.0
-Classifier: License :: Other/Proprietary License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: httpx (>=0.24,<1.0)
-Requires-Dist: typer (>=0.12,<1.0)
-Description-Content-Type: text/markdown
-
 # Cassis CLI
 
 Run Cassis actions from your CI pipelines:
@@ -25,8 +5,8 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology check` validates the ontology files in your repository with the exact same checks as the Cassis GitHub PR check (YAML parsing, round-trip, import validation) — so you can gate merges in any CI system, not just GitHub.
 - `cassis ontology fmt` rewrites the ontology files in canonical form (think `black`/`gofmt` for the ontology), so hand or agent edits pass the round-trip check.
 - `cassis ontology upload` uploads the ontology files to a Cassis project (full replace) and, by default, publishes them immediately as a new version — so a merge to your main branch can go live in one CI step.
-- `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local YAML files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
-- `cassis ontology pull` and `cassis ontology fmt` also write `<base-path>/AGENTS.md`, the Cassis ontology modeling guide, into the checkout (default `cassis/AGENTS.md`) — a managed file (generated banner; the CLI overwrites local edits) so a repo-aware coding agent loads current Cassis modeling doctrine by convention. It sits inside the ontology directory but is not part of the ontology tree (the CLI reads only `*.yml`/`*.yaml`), so it is never uploaded, validated, or pruned. Commit it alongside your ontology changes. The guide text ships inside the CLI package, so its version tracks the **installed cassis-cli version** — upgrade the CLI (`pip install -U cassis-cli`) and re-run `fmt` to pick up doctrine updates; an unpinned `pip install cassis-cli` in CI gets them automatically. The banner stamps a doctrine version, and the CLI never *downgrades* the file: if the checkout's `AGENTS.md` was written by a newer doctrine (a newer CLI, or Cassis itself on a publish), `fmt`/`pull` leave it in place, print an upgrade notice, and `fmt --check` still passes.
+- `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
+- `cassis ontology pull` and `cassis ontology fmt` also write `<base-path>/AGENTS.md`, the Cassis ontology modeling guide, into the checkout (default `cassis/AGENTS.md`) — a managed file (generated banner; the CLI overwrites local edits) so a repo-aware coding agent loads current Cassis modeling doctrine by convention. It sits inside the ontology directory but is not part of the ontology tree (which is the YAML files plus the domain Markdown files `domains/**/README.md`), so it is never uploaded, validated, or pruned. Commit it alongside your ontology changes. The guide text ships inside the CLI package, so its version tracks the **installed cassis-cli version** — upgrade the CLI (`pip install -U cassis-cli`) and re-run `fmt` to pick up doctrine updates; an unpinned `pip install cassis-cli` in CI gets them automatically. The banner stamps a doctrine version, and the CLI never *downgrades* the file: if the checkout's `AGENTS.md` was written by a newer doctrine (a newer CLI, or Cassis itself on a publish), `fmt`/`pull` leave it in place, print an upgrade notice, and `fmt --check` still passes.
 - The CLI identifies itself to the API (`User-Agent: cassis-cli/<version>`), and successful API responses advertise the newest published version — when you are behind, commands print a one-line upgrade notice on stderr (purely informational; output and exit codes are unchanged).
 - `cassis eval run` runs the project's eval suite against your local ontology files (scored in-memory — nothing is pushed to Cassis) and prints per-question results, so you can test the changes on your git branch before merging.
 - `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
@@ -38,11 +18,21 @@ Run Cassis actions from your CI pipelines:
 pip install cassis-cli
 ```
 
+## Ontology file format
+
+The ontology tree under `<base-path>` (default `cassis/`) is:
+
+- **Project identity** — `project.yml`: the Cassis project id and format version. Written by `pull` and by server-side publish (the contexts that know the id); a local `fmt` won't create it.
+- **Domains** — Markdown files: every domain is the `README.md` of its folder — `domains/README.md` for the root, `domains/<path>/README.md` for each sub-domain. Each has a small YAML frontmatter block (`type`, `title`, `description`) and a Markdown body carrying the domain's `context_md`; a generated section at the bottom links the domain's tables and metrics (kept current by `fmt`/`pull` — edit your prose above it, and the PR check fails if the links are stale, so re-run `fmt`). The layout is a Cassis profile inspired by [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf): the files render on GitHub and read in any Markdown editor, but Cassis validates them strictly (unknown keys are flagged, not preserved).
+- **Tables, joins, metrics** — YAML, unchanged: `tables/<schema>/<table>.yml`, `joins.yml`, `metrics/<name>.yml`.
+
+**Migrating an existing repo** (domains were YAML `_project.yml` / `_domain.yml` before cassis-cli 1.1.0): upgrade and run `cassis ontology fmt` (or `cassis ontology pull` if you have no local edits) — it rewrites the domain files to Markdown and removes the old ones. Review the diff and commit. Cassis reads the old YAML domain files too, so an un-migrated repo keeps working until you convert it. **Uploading requires cassis-cli ≥ 1.1.0** — the server rejects an older CLI (which would drop the Markdown domain files) with a clear upgrade error.
+
 ## Setup
 
 1. Create an API key in Cassis under **Organization settings → API keys** (keys start with `sk-k6-`).
 2. Store it as a CI secret and expose it as `CASSIS_API_KEY`.
-3. For `pull`, `upload` and `eval run`: find the project ID (UUID) in the project's URL and expose it as `CASSIS_PROJECT_ID` (or pass `--project`).
+3. For `pull`, `upload`, `eval run`, `ontology test`, and `eval add-case`: the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID in the project's URL).
 
 ## Usage
 
@@ -132,7 +122,7 @@ cassis ontology fmt --check
 | 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another run already active, out of credits, or `--timeout` reached |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
-2000 YAML files / 5 MB total — far above real ontologies (a few hundred small
+2000 ontology files / 5 MB total — far above real ontologies (a few hundred small
 files). Beyond that the CLI fails fast with exit 2 before uploading anything;
 double-check `--base-path` if you hit it.
 
@@ -222,3 +212,17 @@ ontology-publish:
     CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID
 ```
 
+## About this repository
+
+[github.com/GetCassis/cassis-cli](https://github.com/GetCassis/cassis-cli) is a
+read-only mirror, synced automatically from the Cassis monorepo where the CLI is
+developed. Issues are welcome and watched; pull requests can't be merged here, so
+open an issue (or mail tech.admin@getcassis.com) and we'll port the patch upstream
+with credit.
+
+Only the CLI is open source. The Cassis backend it talks to is proprietary and
+requires an account.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).

{cassis_cli-1.0.0 → cassis_cli-1.1.1}/cassis_cli/__init__.py

@@ -1,3 +1,3 @@
 """Cassis CLI — run Cassis actions from your CI pipelines."""
 
-__version__ = "1.0.0"
+__version__ = "1.1.1"

{cassis_cli-1.0.0 → cassis_cli-1.1.1}/cassis_cli/api.py

@@ -191,6 +191,8 @@ def post_ontology_import(
         raise AuthError("The Cassis API rejected the API key (invalid or expired).")
     if response.status_code == 400:
         raise UploadValidationError(str(_detail_or_text(response)))
+    if response.status_code == 426:  # this CLI is too old for the server's ontology format
+        raise UploadValidationError(str(_detail_or_text(response)))
     if response.status_code in (403, 404):
         raise _project_scope_error(response)
     if response.status_code >= 400:

cassis_cli-1.1.1/cassis_cli/common.py

@@ -0,0 +1,177 @@
+"""Helpers shared by the `cassis` subcommands (tree collection, auth, exit codes)."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+from uuid import UUID
+
+import typer
+
+# Repository directory the ontology tree is exported under. Must match the
+# project's git-sync "Path" setting in Cassis (default "cassis").
+DEFAULT_BASE_PATH = "cassis"
+
+# Exit codes (documented in the README; stable contract for CI scripts).
+EXIT_OK = 0
+EXIT_VALIDATION_FAILED = 1
+EXIT_USAGE = 2
+EXIT_TRANSPORT = 3
+
+# Request ceilings of the /api/ci file-tree endpoints, mirrored so oversized
+# trees fail fast with a clear message before any upload. Source of truth:
+# backend/app/schemas/ci.py (the server's 422 remains the backstop).
+MAX_FILES = 2000
+MAX_TOTAL_BYTES = 5 * 1024 * 1024
+
+
+def is_ontology_file(rel_path: str) -> bool:
+    """Whether a base-relative path is an ontology file the server reads.
+
+    YAML (``project.yml``, tables, joins, metrics, legacy domains) plus domain
+    Markdown — every domain is the ``README.md`` of its folder, root included
+    (``domains/README.md``), so ``domains/**/README.md`` covers them all. Mirrors
+    the server's ``ontology_fs.is_ontology_tree_file`` (kept in sync by hand —
+    the CLI can't import the backend). Excludes the managed ``AGENTS.md`` and any
+    stray Markdown note, so neither is uploaded nor deleted by ``pull --prune``.
+    """
+    if rel_path.endswith((".yml", ".yaml")):
+        return True
+    return rel_path.startswith("domains/") and rel_path.endswith("/README.md")
+
+
+def is_legacy_domain_file(rel_path: str) -> bool:
+    """Whether a base-relative path is a legacy (pre-Markdown) domain file.
+
+    Used to report the one-time migration to the Markdown domain format, when
+    ``pull``/``fmt`` remove a ``_project.yml``/``_domain.yml`` and write the
+    ``domains/README.md`` (and sub-domain ``README.md``) that replaces it.
+    """
+    return rel_path == "_project.yml" or rel_path.endswith("/_domain.yml")
+
+
+def collect_files(ontology_dir: Path) -> dict[str, str]:
+    """Read every ontology file under the ontology dir, keyed by posix relpath.
+
+    Ontology files are YAML and domain Markdown (see ``is_ontology_file``); the
+    managed ``AGENTS.md`` and stray notes are skipped. Exits 2 (usage) on an
+    unreadable or non-UTF-8 file — a local checkout problem, reported before
+    anything is sent to the API.
+    """
+    files: dict[str, str] = {}
+    for pattern in ("**/*.yml", "**/*.yaml", "**/*.md"):
+        for file in sorted(ontology_dir.glob(pattern)):
+            if not file.is_file():
+                continue
+            rel = file.relative_to(ontology_dir).as_posix()
+            if not is_ontology_file(rel):
+                continue
+            try:
+                files[rel] = file.read_text(encoding="utf-8")
+            except (UnicodeDecodeError, OSError) as exc:
+                typer.secho(f"Cannot read {file}: {exc}", fg=typer.colors.RED, err=True)
+                raise typer.Exit(EXIT_USAGE) from exc
+    return files
+
+
+# project.yml is a two-line machine-written file (`cassis_format_version`, `project_id`);
+# match the id line directly rather than pull in a YAML parser just for this.
+_PROJECT_ID_LINE = re.compile(r"^project_id:\s*['\"]?([^'\"\s]+)['\"]?\s*$")
+
+
+def read_project_id_from_dir(ontology_dir: Path) -> Optional[str]:
+    """Return the ``project_id`` recorded in ``<ontology_dir>/project.yml``, or None."""
+    try:
+        text = (ontology_dir / "project.yml").read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as _exc:  # `as` keeps black from stripping the parens (3.14-only syntax)
+        return None
+    for line in text.splitlines():
+        match = _PROJECT_ID_LINE.match(line.strip())
+        if match:
+            return match.group(1)
+    return None
+
+
+def resolve_project_id(project_id: Optional[str], ontology_dir: Path) -> str:
+    """Resolve the target project id, defaulting to the checkout's ``project.yml``.
+
+    Precedence: an explicit ``--project`` / ``CASSIS_PROJECT_ID`` wins; otherwise
+    the ``project_id`` recorded in ``<base-path>/project.yml`` (written by
+    ``pull`` / publish) is used, and where it came from is noted on stderr so a
+    stale value in a copied repo is visible. Exits 2 (usage) when neither is
+    available or the value isn't a UUID.
+    """
+    from_file = False
+    if not project_id:
+        project_id = read_project_id_from_dir(ontology_dir)
+        from_file = project_id is not None
+    if not project_id:
+        typer.secho(
+            f"No project. Pass --project (or set CASSIS_PROJECT_ID), or run in a checkout whose "
+            f"{ontology_dir.name}/project.yml records it (written by `cassis ontology pull` or a publish).",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+    try:
+        UUID(project_id)
+    except ValueError:
+        typer.secho(f"--project must be a project ID (UUID), got {project_id!r}.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+    if from_file:
+        typer.secho(f"Using project {project_id} from {ontology_dir.name}/project.yml.", fg=typer.colors.CYAN, err=True)
+    return project_id
+
+
+def require_api_key(api_key: Optional[str]) -> str:
+    """Exit 2 (usage) when no API key was provided."""
+    if not api_key:
+        typer.secho(
+            "No API key. Set CASSIS_API_KEY or pass --api-key "
+            "(create one in Cassis under Organization settings -> API keys).",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+    return api_key
+
+
+def collect_tree(path: Path, base_path: str) -> "tuple[dict[str, str], str]":
+    """Resolve the ontology dir under the checkout and read its file tree.
+
+    Returns ``(files, normalized_base_path)``. Exits 2 (usage) on an empty or
+    missing dir, or a tree beyond the API request ceilings — all local checkout
+    problems, reported before anything is sent to the API.
+    """
+    base_path = base_path.strip().strip("/")
+    if not base_path:
+        typer.secho("--base-path must not be empty.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+
+    ontology_dir = path / Path(base_path)
+    if not ontology_dir.is_dir():
+        typer.secho(
+            f"No {base_path}/ directory found under {path}. "
+            "If the project exports to a custom path, pass it with --base-path (or CASSIS_BASE_PATH).",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+
+    files = collect_files(ontology_dir)
+    if not files:
+        typer.secho(f"No ontology files found under {ontology_dir}.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+
+    total_bytes = sum(len(content.encode()) for content in files.values())
+    if len(files) > MAX_FILES or total_bytes > MAX_TOTAL_BYTES:
+        typer.secho(
+            f"Ontology tree too large: {len(files)} files / {total_bytes / (1024 * 1024):.1f} MB "
+            f"(limits: {MAX_FILES} files / {MAX_TOTAL_BYTES // (1024 * 1024)} MB). "
+            "Check that --base-path points at the ontology directory, not a larger tree.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+    return files, base_path

{cassis_cli-1.0.0 → cassis_cli-1.1.1}/cassis_cli/eval.py

@@ -8,7 +8,6 @@ import subprocess
 import time
 from pathlib import Path
 from typing import Any, Optional
-from uuid import UUID
 
 import typer
 from cassis_cli.api import (
@@ -33,6 +32,7 @@ from cassis_cli.common import (
     EXIT_VALIDATION_FAILED,
     collect_tree,
     require_api_key,
+    resolve_project_id,
 )
 
 app = typer.Typer(no_args_is_help=True, help="Eval commands.")
@@ -144,11 +144,15 @@ def _print_summary(run: dict[str, Any]) -> None:
 
 @app.command(name="add-case")
 def add_case(
-    project_id: str = typer.Option(
-        ...,
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository checkout root (holds <base-path>/project.yml for the --project default).",
+    ),
+    project_id: Optional[str] = typer.Option(
+        None,
         "--project",
         envvar="CASSIS_PROJECT_ID",
-        help="Target Cassis project ID (UUID, shown in the project's URL).",
+        help="Target Cassis project ID (UUID). Defaults to the id in <base-path>/project.yml.",
     ),
     question: str = typer.Option(
         ...,
@@ -173,6 +177,12 @@ def add_case(
         envvar="CASSIS_API_URL",
         help="Cassis API base URL.",
     ),
+    base_path: str = typer.Option(
+        DEFAULT_BASE_PATH,
+        "--base-path",
+        envvar="CASSIS_BASE_PATH",
+        help="Repository directory the ontology is exported under (holds project.yml for the --project default).",
+    ),
     json_output: bool = typer.Option(False, "--json", help="Print the created case as raw JSON."),
 ) -> None:
     """Add a gold test case to the project's eval suite.
@@ -185,11 +195,7 @@ def add_case(
     run, 2 on usage errors, 3 on transport/API errors.
     """
     api_key = require_api_key(api_key)
-    try:
-        UUID(project_id)
-    except ValueError:
-        typer.secho(f"--project must be a project ID (UUID), got {project_id!r}.", fg=typer.colors.RED, err=True)
-        raise typer.Exit(EXIT_USAGE)
+    project_id = resolve_project_id(project_id, path / Path(base_path))
     if not question.strip() or not gold_sql.strip():
         typer.secho("--question and --gold-sql must not be empty.", fg=typer.colors.RED, err=True)
         raise typer.Exit(EXIT_USAGE)
@@ -221,11 +227,11 @@ def run(
         Path("."),
         help="Repository checkout root (the directory containing the ontology export path).",
     ),
-    project_id: str = typer.Option(
-        ...,
+    project_id: Optional[str] = typer.Option(
+        None,
         "--project",
         envvar="CASSIS_PROJECT_ID",
-        help="Target Cassis project ID (UUID, shown in the project's URL).",
+        help="Target Cassis project ID (UUID). Defaults to the id in <base-path>/project.yml.",
     ),
     api_key: Optional[str] = typer.Option(
         None,
@@ -272,18 +278,13 @@ def run(
 ) -> None:
     """Run the project's eval suite against your local ontology files.
 
-    Uploads the local YAML tree and scores it in-memory — nothing is pushed or
+    Uploads the local ontology file tree and scores it in-memory — nothing is pushed or
     persisted in Cassis besides the eval run itself. With --branch, runs against
     an existing Cassis branch instead (no files are sent). Exits 0 when the run
     completes with every case passed, 1 on any failed case / failed run /
     invalid tree, 2 on usage errors, 3 on transport errors or --timeout.
     """
     api_key = require_api_key(api_key)
-    try:
-        UUID(project_id)
-    except ValueError:
-        typer.secho(f"--project must be a project ID (UUID), got {project_id!r}.", fg=typer.colors.RED, err=True)
-        raise typer.Exit(EXIT_USAGE)
     if branch is not None and label is not None:
         typer.secho(
             "--label cannot be used with --branch: branch runs are labelled with the branch name.",
@@ -297,6 +298,7 @@ def run(
         files, base_path = collect_tree(path, base_path)
         if label is None:
             label = _git_branch(path)
+    project_id = resolve_project_id(project_id, path / Path(base_path))
 
     try:
         run_record = post_eval_run_start(

{cassis_cli-1.0.0 → cassis_cli-1.1.1}/cassis_cli/guide.py

@@ -6,7 +6,7 @@ identical — the backend image doesn't ship ``docs/``, so the CLI carries its o
 copy). ``pull`` writes it into the checkout as ``<base_path>/AGENTS.md`` and
 ``fmt`` keeps it canonical, so a repo-aware agent loads current Cassis modeling
 doctrine by convention. The file is managed: a banner marks it generated and the
-CLI overwrites local edits, exactly as ``fmt`` rewrites drifted ontology YAML.
+CLI overwrites local edits, exactly as ``fmt`` rewrites drifted ontology files.
 
 Two writers manage the file — this CLI and the Cassis server's git export — and
 they may run different doctrine versions (the guide ships inside each). The
@@ -31,7 +31,7 @@ GUIDE_FILENAME = "AGENTS.md"
 # Monotonic version of the doctrine text below. Bump it whenever
 # ontology_design_guide.md changes (a backend test enforces the pairing) — it
 # is what lets an older writer recognize a newer guide and leave it alone.
-DOCTRINE_VERSION = 1
+DOCTRINE_VERSION = 4
 
 # Must stay byte-identical to backend/app/services/ontology_guide.py::_BANNER —
 # the server-side git export writes the same file, and differing banners would

{cassis_cli-1.0.0 → cassis_cli-1.1.1}/cassis_cli/ontology.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 import json
 from pathlib import Path
 from typing import List, Optional
-from uuid import UUID
 
 import typer
 from cassis_cli.api import (
@@ -29,7 +28,9 @@ from cassis_cli.common import (
 )
 from cassis_cli.common import collect_files as _collect_files
 from cassis_cli.common import collect_tree as _collect_tree
+from cassis_cli.common import is_legacy_domain_file as _is_legacy_domain_file
 from cassis_cli.common import require_api_key as _require_api_key
+from cassis_cli.common import resolve_project_id as _resolve_project_id
 from cassis_cli.guide import DOCTRINE_VERSION, GUIDE_FILENAME, guide_status, refresh_guide
 
 app = typer.Typer(no_args_is_help=True, help="Ontology commands.")
@@ -113,11 +114,11 @@ def pull(
         Path("."),
         help="Repository checkout root (the directory containing the ontology export path).",
     ),
-    project_id: str = typer.Option(
-        ...,
+    project_id: Optional[str] = typer.Option(
+        None,
         "--project",
         envvar="CASSIS_PROJECT_ID",
-        help="Source Cassis project ID (UUID, shown in the project's URL).",
+        help="Source Cassis project ID (UUID). Defaults to the id in <base-path>/project.yml.",
     ),
     api_key: Optional[str] = typer.Option(
         None,
@@ -140,28 +141,24 @@ def pull(
     prune: bool = typer.Option(
         True,
         "--prune/--no-prune",
-        help="Delete local YAML files that no longer exist in the project's ontology (default: prune).",
+        help="Delete local ontology files that no longer exist in the project's ontology (default: prune).",
     ),
     json_output: bool = typer.Option(False, "--json", help="Print a JSON summary of written/deleted files."),
 ) -> None:
     """Download the project's unpublished ontology into a repository checkout.
 
-    Writes the ontology YAML tree under the export path (full sync: files are
-    overwritten and, unless --no-prune, stale local YAML files are deleted, so
-    the checkout ends up matching the project exactly). Review the changes with
+    Writes the ontology tree under the export path (full sync: files are
+    overwritten and, unless --no-prune, stale local ontology files are deleted,
+    so the checkout ends up matching the project exactly). Review the changes with
     git diff before committing. Exits 0 on success, 2 on usage errors, 3 on
     transport/API errors.
     """
     api_key = _require_api_key(api_key)
-    try:
-        UUID(project_id)
-    except ValueError:
-        typer.secho(f"--project must be a project ID (UUID), got {project_id!r}.", fg=typer.colors.RED, err=True)
-        raise typer.Exit(EXIT_USAGE)
     base_path = base_path.strip().strip("/")
     if not base_path:
         typer.secho("--base-path must not be empty.", fg=typer.colors.RED, err=True)
         raise typer.Exit(EXIT_USAGE)
+    project_id = _resolve_project_id(project_id, path / Path(base_path))
 
     try:
         files = get_ontology_export(api_url=api_url, api_key=api_key, project_id=project_id)
@@ -221,6 +218,13 @@ def pull(
         if guide_written:
             summary += f"; wrote {base_path}/{GUIDE_FILENAME}"
         typer.secho(f"{summary}.", fg=typer.colors.GREEN)
+        migrated = sum(1 for rel in deleted if _is_legacy_domain_file(rel))
+        if migrated:
+            typer.secho(
+                f"  Migrated {migrated} domain(s) to Markdown README.md files; "
+                "the old _domain.yml / _project.yml were removed. Review the diff before committing.",
+                fg=typer.colors.YELLOW,
+            )
     raise typer.Exit(EXIT_OK)
 
 
@@ -230,11 +234,11 @@ def upload(
         Path("."),
         help="Repository checkout root (the directory containing the ontology export path).",
     ),
-    project_id: str = typer.Option(
-        ...,
+    project_id: Optional[str] = typer.Option(
+        None,
         "--project",
         envvar="CASSIS_PROJECT_ID",
-        help="Target Cassis project ID (UUID, shown in the project's URL).",
+        help="Target Cassis project ID (UUID). Defaults to the id in <base-path>/project.yml.",
     ),
     api_key: Optional[str] = typer.Option(
         None,
@@ -270,12 +274,8 @@ def upload(
     usage errors, 3 on transport/API errors.
     """
     api_key = _require_api_key(api_key)
-    try:
-        UUID(project_id)
-    except ValueError:
-        typer.secho(f"--project must be a project ID (UUID), got {project_id!r}.", fg=typer.colors.RED, err=True)
-        raise typer.Exit(EXIT_USAGE)
     files, base_path = _collect_tree(path, base_path)
+    project_id = _resolve_project_id(project_id, path / Path(base_path))
 
     try:
         result = post_ontology_import(
@@ -377,7 +377,7 @@ def fmt(
 
     changed = result["changed_paths"]
     removed = result["removed_paths"]
-    # The managed AGENTS.md guide is canonicalized alongside the YAML tree
+    # The managed AGENTS.md guide is canonicalized alongside the ontology tree
     # (it isn't in the tree, so the server round-trip above never sees it).
     # A guide stamped with a NEWER doctrine than this CLI carries is left
     # alone and does not fail --check: the repo is fine, the CLI is old.
@@ -422,6 +422,13 @@ def fmt(
             + ". Review the diff: fields Cassis does not recognize are dropped.",
             fg=typer.colors.YELLOW,
         )
+        migrated = sum(1 for p in removed if _is_legacy_domain_file(p))
+        if migrated:
+            typer.secho(
+                f"Migrated {migrated} domain(s) to Markdown README.md files; "
+                "the old _domain.yml / _project.yml were removed.",
+                fg=typer.colors.YELLOW,
+            )
     else:
         # Only the guide was refreshed — the "rewrote ..." line above already said so.
         typer.secho(f"✓ {len(files)} file(s) already canonical.", fg=typer.colors.GREEN)
@@ -440,11 +447,11 @@ def test(
         "-q",
         help="Natural-language question to probe (repeat for several).",
     ),
-    project_id: str = typer.Option(
-        ...,
+    project_id: Optional[str] = typer.Option(
+        None,
         "--project",
         envvar="CASSIS_PROJECT_ID",
-        help="Target Cassis project ID (UUID, shown in the project's URL).",
+        help="Target Cassis project ID (UUID). Defaults to the id in <base-path>/project.yml.",
     ),
     api_key: Optional[str] = typer.Option(
         None,
@@ -478,12 +485,8 @@ def test(
     invalid or a probe failed, 2 on usage errors, 3 on transport errors.
     """
     api_key = _require_api_key(api_key)
-    try:
-        UUID(project_id)
-    except ValueError:
-        typer.secho(f"--project must be a project ID (UUID), got {project_id!r}.", fg=typer.colors.RED, err=True)
-        raise typer.Exit(EXIT_USAGE)
     files, base_path = _collect_tree(path, base_path)
+    project_id = _resolve_project_id(project_id, path / Path(base_path))
 
     outcomes: "list[dict]" = []
     failed = False

{cassis_cli-1.0.0 → cassis_cli-1.1.1}/cassis_cli/ontology_design_guide.md

@@ -13,13 +13,13 @@ Read this before proposing an ontology change.
 ## 1. What a Cassis ontology is
 
 The ontology is the curated business context the agent uses to translate a
-natural-language question into SQL. It has five kinds of object plus one
-project-level field, edited as YAML files under the repository's ontology
-directory (`cassis/` by default):
+natural-language question into SQL. It has five kinds of object plus a project-level root context, edited as
+files under the repository's ontology directory (`cassis/` by default) —
+domains as Markdown, everything else as YAML:
 
 | Layer | What it is | Key fields |
 |---|---|---|
-| **Root context** (`_project.yml → context_md`) | One free-text block, always in the agent's prompt | markdown |
+| **Root context** (`domains/README.md` body) | One free-text block, always in the agent's prompt | markdown |
 | **Domains** | A navigable tree grouping the business by subject area | `path`, `display_name`, `description`, `context_md` |
 | **Tables** | A physical warehouse table (introspected) or a virtual one (SQL-defined) placed in a domain | `name` (`schema.TABLE`), `description`, `synonyms`, `grain`, columns |
 | **Columns** | Enrichment on a table's columns | `description`, `unit`, `synonyms` |
@@ -31,11 +31,12 @@ On disk, the export layout is fixed — create each object in its canonical home
 
 ```
 cassis/                          (the git-sync base path)
-  _project.yml                   root context (context_md), project display name
-  domains/<path>/_domain.yml     one per domain, nested by path
-  tables/<schema>/<table>.yml    one per table, columns inline
-  metrics/<name>.yml             one per metric
-  joins.yml                      ALL joins, one list in one file
+  project.yml                    project identity: project id + Cassis format version (written by publish / pull)
+  domains/README.md              root domain (path ""): frontmatter (type/title/description) + context_md body
+  domains/<path>/README.md       one per sub-domain, nested by path (same Markdown format)
+  tables/<schema>/<table>.yml    one per table, columns inline (YAML)
+  metrics/<name>.yml             one per metric (YAML)
+  joins.yml                      ALL joins, one list in one file (YAML)
 ```
 
 Joins and metrics are never embedded inside a table's file, and a table's file
@@ -45,7 +46,7 @@ time (run `cassis ontology fmt` to see what would be lost).
 The **published** ontology is an immutable numbered snapshot — what production
 answers from. The **unpublished** ontology is the editable state (the published
 base plus unpublished changes). In a git-synced project the repository *is* the
-edit surface: you edit the YAML, open a pull request, and merging syncs and
+edit surface: you edit the files, open a pull request, and merging syncs and
 publishes it.
 
 Physical tables and their columns come from schema introspection — you never
@@ -151,6 +152,12 @@ its own — an empty navigational domain is just noise. Every table and every
 metric names a `domain_path` that must resolve to a domain you've declared (or the
 root, `""`).
 
+Each domain is a Markdown file (`domains/<path>/README.md`, or `domains/README.md`
+for the root). Its YAML frontmatter holds the structured fields — `type: Domain`,
+`title:` (the display name), `description:` — and the Markdown body **is** the
+domain's `context_md`. Write the display name as `title`, not `display_name`: an
+unrecognized frontmatter key is dropped on sync.
+
 A useful convention inside `context_md`: a `## Terms` section for the domain's
 vocabulary and disambiguation, and a `## Notes` section for routing hints and
 scope caveats. Omit either if you have nothing for it.
@@ -167,7 +174,7 @@ scope caveats. Omit either if you have nothing for it.
 - Markdown **links** to related domains, using the resolvable domain path
   (`[berries](play/features/berries)`), not a bare filename.
 
-**Root context** — the `context_md` in `_project.yml`, injected into every
+**Root context** — the body of the root domain (`domains/README.md`), injected into every
 conversation — **holds only what applies across almost every query:** corporate
 identity, the core entity hierarchy (how the central models relate — e.g. "users
 belong to companies via enrollments; primary enrollments are employees, partner
@@ -379,13 +386,37 @@ description, so a wrong example is worse than none.
 
 ---
 
-## 12. Working in a git-synced repo
+## 12. Extension passes: structure before content
+
+Adding a source or a whole subject area inverts the scoping bullet above. §11 is
+written for maintenance edits, where a structural change is genuinely adjacent;
+on an extension pass the tree *is* the change — every table and metric names a
+`domain_path`, so content filled into a hierarchy you already doubt all has to
+move. Same human opt-in, front-loaded:
+
+1. **Scope.** Agree what is being added, from which sources, in what order.
+2. **Structure.** Evaluate the existing hierarchy against what is arriving and
+   propose the tree changes — new domains, splits, moves — for approval *before*
+   any content. On approval, create the new domain files frontmatter-only (empty
+   body), so every `domain_path` resolves while you fill.
+3. **Fill bottom-up.** Column and table facts, then metrics and joins, then each
+   domain README body last, written from what is left over. That residue is by
+   construction the cross-table connective tissue domain level owns, so the order
+   enforces the one-home rule instead of leaving it to vigilance. Bottom-up is an
+   authoring order, not a holding rule: a fact learned out of order still lands at
+   its owning layer immediately (§11). If filling shows the approved tree is wrong
+   — a domain overloads, or wants to split — stop and return to 2 rather than keep
+   filling into it.
+
+---
+
+## 13. Working in a git-synced repo
 
-The repository is the source of truth. Edit the YAML, then verify before opening
+The repository is the source of truth. Edit the files, then verify before opening
 a pull request — the CLI runs the same checks the platform does, from your
 checkout:
 
-- `cassis ontology check` — validate the files (YAML parse, round-trip, semantic
+- `cassis ontology check` — validate the files (parse, round-trip, semantic
   checks); the same gate that runs on the pull request.
 - `cassis ontology fmt` — rewrite the files in canonical form, so hand or agent
   edits round-trip cleanly and any dropped/unknown fields become visible in the

{cassis_cli-1.0.0 → cassis_cli-1.1.1}/pyproject.toml

@@ -1,11 +1,17 @@
 [project]
 name = "cassis-cli"
-version = "1.0.0"
+version = "1.1.1"
 description = "Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines"
 readme = "README.md"
-license = { text = "Proprietary" }
+license = { text = "Apache-2.0" }
 authors = [{ name = "Cassis", email = "tech.admin@getcassis.com" }]
 keywords = ["cassis", "ontology", "ci", "text-to-sql"]
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Database",
+]
 # Customer CI images — keep this floor low and the code 3.10-compatible,
 # regardless of the monorepo's own Python pin.
 requires-python = ">=3.10,<4.0"
@@ -14,6 +20,11 @@ dependencies = [
     "httpx (>=0.24,<1.0)",
 ]
 
+[project.urls]
+Homepage = "https://getcassis.com"
+Repository = "https://github.com/GetCassis/cassis-cli"
+Documentation = "https://github.com/GetCassis/cassis-cli#readme"
+
 [project.scripts]
 cassis = "cassis_cli.main:app"
 

cassis_cli-1.0.0/cassis_cli/common.py

@@ -1,95 +0,0 @@
-"""Helpers shared by the `cassis` subcommands (tree collection, auth, exit codes)."""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Optional
-
-import typer
-
-# Repository directory the ontology tree is exported under. Must match the
-# project's git-sync "Path" setting in Cassis (default "cassis").
-DEFAULT_BASE_PATH = "cassis"
-
-# Exit codes (documented in the README; stable contract for CI scripts).
-EXIT_OK = 0
-EXIT_VALIDATION_FAILED = 1
-EXIT_USAGE = 2
-EXIT_TRANSPORT = 3
-
-# Request ceilings of the /api/ci file-tree endpoints, mirrored so oversized
-# trees fail fast with a clear message before any upload. Source of truth:
-# backend/app/schemas/ci.py (the server's 422 remains the backstop).
-MAX_FILES = 2000
-MAX_TOTAL_BYTES = 5 * 1024 * 1024
-
-
-def collect_files(ontology_dir: Path) -> dict[str, str]:
-    """Read every YAML file under the ontology dir, keyed by posix relpath.
-
-    Exits 2 (usage) on an unreadable or non-UTF-8 file — a local checkout
-    problem, reported before anything is sent to the API.
-    """
-    files: dict[str, str] = {}
-    for pattern in ("**/*.yml", "**/*.yaml"):
-        for file in sorted(ontology_dir.glob(pattern)):
-            if file.is_file():
-                try:
-                    files[file.relative_to(ontology_dir).as_posix()] = file.read_text(encoding="utf-8")
-                except (UnicodeDecodeError, OSError) as exc:
-                    typer.secho(f"Cannot read {file}: {exc}", fg=typer.colors.RED, err=True)
-                    raise typer.Exit(EXIT_USAGE) from exc
-    return files
-
-
-def require_api_key(api_key: Optional[str]) -> str:
-    """Exit 2 (usage) when no API key was provided."""
-    if not api_key:
-        typer.secho(
-            "No API key. Set CASSIS_API_KEY or pass --api-key "
-            "(create one in Cassis under Organization settings -> API keys).",
-            fg=typer.colors.RED,
-            err=True,
-        )
-        raise typer.Exit(EXIT_USAGE)
-    return api_key
-
-
-def collect_tree(path: Path, base_path: str) -> "tuple[dict[str, str], str]":
-    """Resolve the ontology dir under the checkout and read its YAML tree.
-
-    Returns ``(files, normalized_base_path)``. Exits 2 (usage) on an empty or
-    missing dir, or a tree beyond the API request ceilings — all local checkout
-    problems, reported before anything is sent to the API.
-    """
-    base_path = base_path.strip().strip("/")
-    if not base_path:
-        typer.secho("--base-path must not be empty.", fg=typer.colors.RED, err=True)
-        raise typer.Exit(EXIT_USAGE)
-
-    ontology_dir = path / Path(base_path)
-    if not ontology_dir.is_dir():
-        typer.secho(
-            f"No {base_path}/ directory found under {path}. "
-            "If the project exports to a custom path, pass it with --base-path (or CASSIS_BASE_PATH).",
-            fg=typer.colors.RED,
-            err=True,
-        )
-        raise typer.Exit(EXIT_USAGE)
-
-    files = collect_files(ontology_dir)
-    if not files:
-        typer.secho(f"No YAML files found under {ontology_dir}.", fg=typer.colors.RED, err=True)
-        raise typer.Exit(EXIT_USAGE)
-
-    total_bytes = sum(len(content.encode()) for content in files.values())
-    if len(files) > MAX_FILES or total_bytes > MAX_TOTAL_BYTES:
-        typer.secho(
-            f"Ontology tree too large: {len(files)} files / {total_bytes / (1024 * 1024):.1f} MB "
-            f"(limits: {MAX_FILES} files / {MAX_TOTAL_BYTES // (1024 * 1024)} MB). "
-            "Check that --base-path points at the ontology directory, not a larger tree.",
-            fg=typer.colors.RED,
-            err=True,
-        )
-        raise typer.Exit(EXIT_USAGE)
-    return files, base_path