refactor: organize SDK by language (#27)

* docs: define language-first SDK layout

* docs: plan SDK language layout migration

* test: define SDK repository layout contract

* refactor: move Rust SDK workspace under rust

* refactor: move Java SDK module under java

* ci: align automation with language directories

* docs: document language-first SDK layout

* fix: anchor documentation contract at repository root

* docs: update layout plan after dependency fix

* fix: preserve required Java CI check

* fix: preserve repository-root path contracts

Author: JamesbbBriz

.github/dependabot.yml

@@ -1,7 +1,16 @@
 version: 2
 updates:
+  - package-ecosystem: cargo
+    directory: /rust
+    schedule:
+      interval: weekly
+      day: monday
+      time: "08:30"
+      timezone: Australia/Sydney
+    open-pull-requests-limit: 5
+
   - package-ecosystem: maven
-    directory: /
+    directory: /java
     schedule:
       interval: weekly
       day: monday

.github/pull_request_template.md

@@ -8,10 +8,11 @@
 
 ## Verification
 
-- [ ] `mvn test`
-- [ ] `mvn verify`
-- [ ] `mvn spotless:check`
-- [ ] `mvn checkstyle:check`
+- [ ] `cd java && mvn test`
+- [ ] `cd java && mvn verify`
+- [ ] `cd java && mvn spotless:check`
+- [ ] `cd java && mvn checkstyle:check`
+- [ ] `cd rust && cargo test`
 - [ ] Documentation updated, if behavior changed
 
 ## Contract Checklist

.github/workflows/ci.yml

@@ -14,10 +14,21 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  memtruth-sdk:
-    name: memtruth-sdk (rust 1.95)
+  repository-layout:
+    name: repository layout
     runs-on: ubuntu-latest
 
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Verify language-first layout
+        run: scripts/check-repository-layout.sh
+
+  rust-sdk:
+    name: Rust SDK (1.95)
+    runs-on: ubuntu-latest
+    needs: repository-layout
+
     steps:
       - uses: actions/checkout@v6
 
@@ -27,20 +38,21 @@ jobs:
           rustup default 1.95.0
 
       - name: Format
-        working-directory: memtruth-sdk
+        working-directory: rust
         run: cargo fmt --check
 
       - name: Test
-        working-directory: memtruth-sdk
+        working-directory: rust
         run: cargo test
 
       - name: Clippy
-        working-directory: memtruth-sdk
+        working-directory: rust
         run: cargo clippy --all-targets -- -D warnings
 
-  build:
+  java-sdk:
     name: build (${{ matrix.java }})
     runs-on: ubuntu-latest
+    needs: repository-layout
     strategy:
       fail-fast: false
       matrix:
@@ -55,14 +67,18 @@ jobs:
           distribution: temurin
           java-version: ${{ matrix.java }}
           cache: maven
+          cache-dependency-path: java/pom.xml
 
       - name: Style and static checks
+        working-directory: java
         run: mvn -B -ntp spotless:check checkstyle:check
 
       - name: Verify (unit + integration + recorded LLM + coverage)
+        working-directory: java
         run: mvn -B -ntp verify -P recorded
 
       - name: Resolve project version
+        working-directory: java
         run: echo "PROJECT_VERSION=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.version)" >> "$GITHUB_ENV"
 
       - name: Compile quickstart against packaged SDK
@@ -75,6 +91,7 @@ jobs:
         run: scripts/smoke-cli-release.sh --version "${PROJECT_VERSION}"
 
       - name: Generate SBOM
+        working-directory: java
         run: mvn -B -ntp -DskipTests cyclonedx:makeAggregateBom
 
       - name: Upload surefire reports on failure

.github/workflows/javadocs.yml

@@ -32,14 +32,16 @@ jobs:
           distribution: temurin
           java-version: '25'
           cache: maven
+          cache-dependency-path: java/pom.xml
 
       - name: Generate Javadocs
+        working-directory: java
         run: mvn -B -ntp javadoc:javadoc
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v5
         with:
-          path: target/site/apidocs
+          path: java/target/site/apidocs
 
       - name: Deploy to GitHub Pages
         id: deployment

.github/workflows/nightly-live.yml

@@ -27,8 +27,10 @@ jobs:
           distribution: temurin
           java-version: '25'
           cache: maven
+          cache-dependency-path: java/pom.xml
 
       - name: Run bounded live LLM smoke
+        working-directory: java
         run: mvn -B -ntp -P live -Dit.test=ExternalLlmSmokeIT failsafe:integration-test failsafe:verify
         env:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

.github/workflows/release.yml

@@ -28,13 +28,15 @@ jobs:
           distribution: temurin
           java-version: '25'
           cache: maven
+          cache-dependency-path: java/pom.xml
           server-id: central
           server-username: MAVEN_USERNAME
           server-password: MAVEN_PASSWORD
           gpg-private-key: ${{ secrets.OSSRH_GPG_PRIVATE_KEY }}
           gpg-passphrase: MAVEN_GPG_PASSPHRASE
 
       - name: Verify release commit
+        working-directory: java
         run: mvn -B -ntp spotless:check checkstyle:check verify -P recorded
 
       - name: Package CLI release artifacts
@@ -44,11 +46,13 @@ jobs:
         run: scripts/smoke-cli-release.sh --version "${GITHUB_REF_NAME#v}"
 
       - name: Generate CycloneDX SBOM
+        working-directory: java
         run: |
           mvn -B -ntp -DskipTests cyclonedx:makeAggregateBom
-          cp target/bom.json dist/doctruth-${GITHUB_REF_NAME#v}-sbom.cdx.json
+          cp target/bom.json ../dist/doctruth-${GITHUB_REF_NAME#v}-sbom.cdx.json
 
       - name: Deploy to Sonatype Central Portal
+        working-directory: java
         run: mvn -B -ntp -P release deploy -DskipTests
         env:
           MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
@@ -63,9 +67,9 @@ jobs:
           path: |
             dist/*
             dist/homebrew/*
-            target/*.jar
-            target/*.jar.asc
-            target/*.pom
+            java/target/*.jar
+            java/target/*.jar.asc
+            java/target/*.pom
           retention-days: 30
 
       - name: Create GitHub Release

CHANGELOG.md

@@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Repositioned the repository as Memtruth SDK while keeping the existing
   `doctruth` Java package, Maven coordinate, CLI command, and release artifact
   names as compatibility surfaces.
+- Organized the public SDK repository into `rust/` and `java/` language
+  workspaces, with shared docs, examples, configuration, and release scripts at
+  the root.
 
 ### Fixed
 

CONTRIBUTING.md

@@ -37,10 +37,11 @@ Public API compatibility:
   public API, regenerate it with:
 
 ```bash
+cd java
 mvn -Dtest=ai.doctruth.PublicApiSnapshotTest -Ddoctruth.updatePublicApiSnapshot=true test
 ```
 
-Review `src/test/resources/ai/doctruth/public-api-snapshot.txt` before committing.
+Review `java/src/test/resources/ai/doctruth/public-api-snapshot.txt` before committing.
 
 Scope boundaries:
 
@@ -78,11 +79,21 @@ export PATH=$JAVA_HOME/bin:$PATH
 Build + test:
 
 ```bash
+cd java
 mvn test                 # unit tests only (~3s)
 mvn verify               # unit + integration + JaCoCo coverage gate (~10s)
 mvn spotless:apply       # auto-format
 ```
 
+Rust workspace:
+
+```bash
+cd rust
+cargo fmt --check
+cargo test
+cargo clippy --all-targets -- -D warnings
+```
+
 `mvn verify` runs the JaCoCo coverage check (line ≥ 90% and branch ≥ 79%
 bundle-wide, excluding `ai.doctruth.internal.providers.*` wire records). Lower
 the gate only by ADR.
@@ -96,11 +107,11 @@ OpenAI chat-completions shape. Add a new first-class provider only when the
 vendor has materially different structured-output semantics, authentication,
 retry behavior, or audit metadata.
 
-1. **Wire records** — `src/main/java/ai/doctruth/internal/providers/<vendor>/wire/` with one record per request/response shape (immutable, Jackson-annotated).
-2. **HTTP client** — `<Vendor>HttpClient` in `src/main/java/ai/doctruth/internal/providers/<vendor>/`, hand-rolled on `java.net.http.HttpClient`. No vendor SDK on the classpath.
+1. **Wire records** — `java/src/main/java/ai/doctruth/internal/providers/<vendor>/wire/` with one record per request/response shape (immutable, Jackson-annotated).
+2. **HTTP client** — `<Vendor>HttpClient` in `java/src/main/java/ai/doctruth/internal/providers/<vendor>/`, hand-rolled on `java.net.http.HttpClient`. No vendor SDK on the classpath.
 3. **Sealed `LlmProvider`** — add the new permits clause. This is a public-API change → MAJOR version bump (or ship as a separate artifact post-1.0).
 4. **Public `<Vendor>Provider` class** — in `ai.doctruth` root package, delegating to the internal `<Vendor>HttpClient`. Mirror the OpenAI-compatible / Anthropic / Gemini shape where possible.
-5. **WireMock-backed test class** — `<Vendor>ProviderHttpTest` exercising happy path, retry, HTTP errors, response validation. Recorded responses go in `src/test/resources/wiremock/<vendor>/`.
+5. **WireMock-backed test class** — `<Vendor>ProviderHttpTest` exercising happy path, retry, HTTP errors, response validation. Recorded responses go in `java/src/test/resources/wiremock/<vendor>/`.
 6. **ADR update** — if the provider introduces an architecturally novel concern (e.g. multimodal request shape, server-sent events), update or add an ADR.
 
 ## How to add an SPI implementation
@@ -117,8 +128,8 @@ Default implementations stay conservative and no-op where appropriate. Custom im
 
 Before opening a PR, confirm:
 
-- [ ] `mvn test` is green
-- [ ] `mvn verify` is green (includes integration tests + JaCoCo gate)
+- [ ] `cd java && mvn test` is green
+- [ ] `cd java && mvn verify` is green (includes integration tests + JaCoCo gate)
 - [ ] No file exceeds 300 LOC; no method body exceeds 30 LOC
 - [ ] No new entries in `<dependencies>` without an ADR in the same PR
 - [ ] Public-API changes flagged in the PR title (e.g. `feat!:` or `BREAKING CHANGE:` footer)

README.es.md

@@ -126,7 +126,7 @@ Memtruth Parse soporta exportaciones comunes de Pydantic v2 JSON Schema, incluye
 Herramienta de migración en build-time:
 
 ```bash
-java -jar target/doctruth-java-0.2.0-alpha-all.jar \
+java -jar java/target/doctruth-java-0.2.0-alpha-all.jar \
   migrate pydantic myapp.schemas:ResumeExtraction \
   -o schemas/resume.schema.json \
   --check
@@ -150,10 +150,10 @@ Los clientes usan `java.net.http.HttpClient` del JDK; no hay SDKs de proveedores
 ## CLI
 
 ```bash
-mvn package -DskipTests
-java -jar target/doctruth-java-0.2.0-alpha-all.jar parse contract.pdf
-java -jar target/doctruth-java-0.2.0-alpha-all.jar schema contract.schema.json
-java -jar target/doctruth-java-0.2.0-alpha-all.jar extract contract.pdf -s contract.schema.json
+mvn -f java/pom.xml package -DskipTests
+java -jar java/target/doctruth-java-0.2.0-alpha-all.jar parse contract.pdf
+java -jar java/target/doctruth-java-0.2.0-alpha-all.jar schema contract.schema.json
+java -jar java/target/doctruth-java-0.2.0-alpha-all.jar extract contract.pdf -s contract.schema.json
 ```
 
 ## Documentación

README.md

@@ -38,12 +38,21 @@ Memtruth Parse is for teams that need to answer one question reliably:
 
 The core boundary is simple: source document in, validated structured output plus evidence trail out.
 
-[`memtruth-sdk`](memtruth-sdk/) is the Rust SDK workspace for corpus contracts,
+[`rust`](rust/) is the Rust SDK workspace for corpus contracts,
 section-aware chunking, retrieval projection, and Vespa preflight diagnostics.
 It is intentionally separate from any server memory layer: document output
 should flow through stable evidence/corpus contracts instead of coupling
 storage, MCP behavior, or hosted services to parser internals.
 
+## Repository Layout
+
+| Path | Responsibility |
+| --- | --- |
+| [`rust/`](rust/) | Rust contracts, chunking, retrieval projection, and Vespa adapters |
+| [`java/`](java/) | Java SDK, CLI, packaging, and `ai.doctruth` compatibility surface |
+| [`docs/`](docs/) | Architecture, contracts, integration guides, and ADRs |
+| [`examples/`](examples/) | Runnable Java integration and no-LLM parsing examples |
+
 Memtruth Parse is framework-agnostic and fits into plain Java, Spring Boot,
 LangChain4j, Spring AI, Quarkus, Micronaut, or any Java service that already
 calls OpenAI, Anthropic, Gemini, DeepSeek, or an OpenAI-compatible model
@@ -125,10 +134,10 @@ The CLI is for first-run inspection, parser debugging, schema checks, and CI
 smoke tests. Parser and schema inspection do not require an LLM key.
 
 ```bash
-mvn package -DskipTests
-java -jar target/doctruth-java-0.2.0-alpha-all.jar parse examples/no-llm-parse/sample-contract.csv
-java -jar target/doctruth-java-0.2.0-alpha-all.jar parse examples/no-llm-parse/sample-contract.csv --json -o parsed.json
-java -jar target/doctruth-java-0.2.0-alpha-all.jar schema examples/pydantic-interop/resume.schema.json
+mvn -f java/pom.xml package -DskipTests
+java -jar java/target/doctruth-java-0.2.0-alpha-all.jar parse examples/no-llm-parse/sample-contract.csv
+java -jar java/target/doctruth-java-0.2.0-alpha-all.jar parse examples/no-llm-parse/sample-contract.csv --json -o parsed.json
+java -jar java/target/doctruth-java-0.2.0-alpha-all.jar schema examples/pydantic-interop/resume.schema.json
 ```
 
 For a copy-pasteable Java parser example that also needs no provider key, see
@@ -258,9 +267,9 @@ doctruth audit .doctruth/runs/<run-id>/audit.json
 
 `0.2.0-alpha` is an early public alpha. The API is usable, tested, and published for feedback, but may still change before `1.0`.
 
-Current verification baseline: `mvn verify` passes with 703 unit tests and the
-tracked integration suite; optional local corpus tests run when `fixtures/` is
-present. Coverage gates are 90% line / 79% branch.
+Java CI runs `cd java && mvn verify -P recorded`; Rust CI runs format, test, and
+clippy gates from `rust/`. Optional local corpus tests run when `fixtures/` is
+present. Java coverage gates are 90% line / 79% branch.
 
 ## License