Add Terra/AnVIL ADR, TDD guide, and acceptance tests for DRS URI support

.github/workflows/pages.yaml

@@ -0,0 +1,88 @@
+name: Publish documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/pages.yaml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install documentation builder
+        run: python -m pip install mkdocs-material==9.6.14
+
+      - name: Select end-user documentation
+        run: |
+          mkdir -p .pages-docs
+          cp docs/index.md .pages-docs/
+          cp docs/quickstart.md .pages-docs/
+          cp docs/getting-started.md .pages-docs/
+          cp docs/commands.md .pages-docs/
+          cp docs/pointer-files.md .pages-docs/
+          cp docs/adding-s3-files.md .pages-docs/
+          cp docs/remove-files.md .pages-docs/
+          cp docs/troubleshooting.md .pages-docs/
+          cp docs/*.png .pages-docs/
+
+      - name: Build documentation and presentation
+        run: |
+          mkdir -p .pages-build
+          npx --yes @marp-team/marp-cli@4.2.3 \
+            docs/anvil-terra-poc-presentation.md \
+            --html \
+            --template bespoke \
+            --output .pages-build/anvil-terra-poc-presentation.html
+          mkdocs build --strict
+          # Keep the standalone Bespoke document byte-for-byte intact. Passing
+          # it through MkDocs is unnecessary for this standalone entry point.
+          cp .pages-build/anvil-terra-poc-presentation.html \
+            _site/anvil-terra-poc-presentation.html
+
+      - name: Verify presentation artifact
+        run: |
+          # A Bespoke deck needs its embedded browser runtime for slide paging.
+          grep -q '<script' _site/anvil-terra-poc-presentation.html
+          grep -q 'bespoke' _site/anvil-terra-poc-presentation.html
+          # Guard code-block contrast against Marp's highlighting stylesheet.
+          grep -q 'pre code.hljs' _site/anvil-terra-poc-presentation.html
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -18,3 +18,9 @@ coverage/unit/
 admin/
 # Ignore any file named .env anywhere in the repository
 .env
+# ignore working dirs, files
+attic/
+patch.txt
+.pages-docs/
+_site/
+

README.md

@@ -42,7 +42,9 @@ At a high level:
 
 ```bash
 git drs install
-git drs remote add gen3 production HTAN_INT/BForePC --cred /path/to/credentials.json
+git drs remote add production https://example-gen3.org --provider gen3 \
+  --scope HTAN_INT/BForePC --auth provider-helper:gen3-profile \
+  --credential file:/path/to/credentials.json
 git drs track "*.bam"
 git add .gitattributes
 git add sample.bam
@@ -63,12 +65,14 @@ The cleaned CLI intentionally removed legacy commands:
   - `git drs download`
 - `git drs pull` is hydration-only
 - `git drs ls-files` is the local file inventory command
-- `git drs remote add gen3` takes scope as `organization/project`
+- the unified `git drs remote add` takes scope through
+  `--scope <organization/project>`
 
 Example:
 
 ```bash
-git drs remote add gen3 production HTAN_INT/BForePC --cred /path/to/credentials.json
+git drs remote add production calypr --scope HTAN_INT/BForePC \
+  --credential file:/path/to/credentials.json
 ```
 
 Current command split:
@@ -91,7 +95,8 @@ Push and pull depend on server-side bucket mapping for the requested scope. That
 | --- | --- |
 | `git drs install` | Install global `git-drs` filter config |
 | `git drs init` | Explicitly initialize or repair repository-local `git-drs` state |
-| `git drs remote add gen3 [remote] <org/project>` | Add or refresh a Gen3/Syfon remote |
+| `git drs remote add <endpoint-or-alias>` | Add a DRS remote (operational: Calypr/Gen3 and Terra; catalog-only: Synapse and CGC) |
+| `git drs preset list` | List the non-secret presets embedded in this release |
 | `git drs remote list` | List configured remotes |
 | `git drs remote remove <name>` | Remove a configured DRS remote |
 | `git drs remote set <name>` | Set the default remote |
@@ -108,10 +113,12 @@ Push and pull depend on server-side bucket mapping for the requested scope. That
 
 ## Documentation
 
+- [Documentation Home](docs/index.md)
 - [Getting Started](docs/getting-started.md)
 - [Commands Reference](docs/commands.md)
 - [Troubleshooting](docs/troubleshooting.md)
 - [Developer Guide](docs/developer-guide.md)
+- [Publishing documentation with GitHub Pages](docs/github-pages.md)
 - [GA4GH DRS Scalability Gaps](docs/ga4gh-drs-scalability-gaps.md)
 
 ## Requirements