calypr · lbeckman314 · Sep 23, 2025 · Sep 23, 2025 · Sep 23, 2025 · Dec 22, 2025
diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml
@@ -0,0 +1,46 @@
+# Check links in documentation on every push and pull request
+# Uses Lychee link checker to find broken links
+
+name: Check Links
+
+on:
+  push:
+  workflow_dispatch:
+  schedule:
+    # Run weekly on Sunday at 0 AM UTC to catch external link changes
-    # Run weekly on Sunday at 0 AM UTC to catch external link changes
+    # Run weekly on Sunday at 09:00 UTC to catch external link changes
-    # Run weekly on Sunday at 0 AM UTC to catch external link changes
+    # Run weekly on Sunday at 09:00 UTC to catch external link changes
+    - cron: '0 9 * * 0'
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  lychee:
+    runs-on: ubuntu-latest
-  pull-requests: write
-  issues: write
-
-jobs:
-  lychee:
-    runs-on: ubuntu-latest
+
+jobs:
+  lychee:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
-  pull-requests: write
-  issues: write
-
-jobs:
-  lychee:
-    runs-on: ubuntu-latest
+
+jobs:
+  lychee:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run Lychee link checker
+        id: lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          # Check all markdown files in docs/ and README.md
+          args: --verbose --no-progress --exclude-private 'docs/**/*.md' 'README.md' '**/*.md'
-          # Check all markdown files in docs/ and README.md
-          args: --verbose --no-progress --exclude-private 'docs/**/*.md' 'README.md' '**/*.md'
+          # Check all Markdown files in the repository
+          args: --verbose --no-progress --exclude-private '**/*.md'
-          # Check all markdown files in docs/ and README.md
-          args: --verbose --no-progress --exclude-private 'docs/**/*.md' 'README.md' '**/*.md'
+          # Check all Markdown files in the repository
+          args: --verbose --no-progress --exclude-private '**/*.md'
+          # Fail on broken links but allow exclusions
+          fail: true
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+
+      - name: Create Issue from Failures
+        if: steps.lychee.outputs.exit_code != 0 && github.event_name == 'schedule'
+        uses: peter-evans/create-issue-from-file@v5
+        with:
+          title: 'Link Checker Report - Broken Links Found'
+          body-file: lychee/out.md
+          labels: |
+            documentation
+            broken-links
+            automated-report
+
diff --git a/docs/.nav.yml b/docs/.nav.yml
@@ -0,0 +1,4 @@
+nav:
+  - Home: index.md
+  - Calypr: calypr/
+  - Tools: tools/
diff --git a/docs/assets/banner.png b/docs/assets/banner.png
diff --git a/docs/assets/banner_fade.png b/docs/assets/banner_fade.png
diff --git a/docs/assets/calypr_family.png b/docs/assets/calypr_family.png
diff --git a/docs/assets/funnel.png b/docs/assets/funnel.png
diff --git a/docs/assets/git-drs.png b/docs/assets/git-drs.png
diff --git a/docs/assets/grip.png b/docs/assets/grip.png
diff --git a/docs/assets/logo.png b/docs/assets/logo.png
diff --git a/docs/calypr/.nav.yml b/docs/calypr/.nav.yml
@@ -0,0 +1,10 @@
+title: Calypr
+nav:
+  - Quick Start Guide: quick-start.md
+  - Troubleshooting & FAQ: troubleshooting.md
+  - Data Management: data-management/
+  - Analysis: analysis/
+  - Data Model: data-model/
+  - Project Management: project-management/
+  - Calypr Admin: calypr-admin/
+  - Website: website/
diff --git a/docs/calypr/analysis/.nav.yml b/docs/calypr/analysis/.nav.yml
@@ -0,0 +1,2 @@
+nav:
+  - Data Querying + Gen3 SDK: query.md
diff --git a/docs/workflows/query.md → docs/calypr/analysis/query.md b/docs/workflows/query.md → docs/calypr/analysis/query.md
@@ -12,20 +12,20 @@ Gen3 supports API access to Files and Metadata, allowing users to download and q
 ## 1. Dependency and Credentials 
 
 
-Prior to installing, check a profile credentials. 
+Prior to querying, ensure your DRS remotes are configured.
 Test:
 ```bash
-g3t ping 
+git drs remote list
 ```
-- will return a list of projects that a profile has access to.
+- will return a list of configured DRS remotes and projects you have access to.
 
 - For new setup or renew of gen3 credentials - Follow steps to configure/re-configure a profile with credentials: 
 
-    - Download an API Key from the [Profile page](https://calypr.ohsu.edu.org/identity) and save it to `~/.gen3/credentials.json`
+    - Download an API Key from the [Profile page](https://calypr-public.ohsu.edu/identity) and save it to `~/.gen3/credentials.json`
 
-    ![Gen3 Profile page](../images/api-key.png)
+    ![Gen3 Profile page](../../images/api-key.png)
 
-    ![Gen3 Credentials](../images/credentials.png)
+    ![Gen3 Credentials](../../images/credentials.png)
 
 
 ## 2. Install

diff --git a/docs/calypr/calypr-admin/.nav.yml b/docs/calypr/calypr-admin/.nav.yml
@@ -0,0 +1,4 @@
+nav:
+  - Add users: add-users.md
+  - Role Based Access Control: approve-requests.md
+  - Creating a Project: creating-project.md
diff --git a/docs/workflows/add-users.md → docs/calypr/calypr-admin/add-users.md b/docs/workflows/add-users.md → docs/calypr/calypr-admin/add-users.md
@@ -3,7 +3,7 @@
 ## Granting user access to a project
 
 Once a project has been created you will have full access to it. 
-The project owner can add additional users to the project using the `g3t collaborator` commands.
+The project owner can add additional users to the project using the `data-client collaborator` commands.
 
 There are two ways to request the addition additional users to the project:
 
@@ -12,15 +12,14 @@ There are two ways to request the addition additional users to the project:
 To give another user full access to the project, run the following:
 
 ```sh
-g3t collaborator add --write  user-can-write@example.com
+data-client collaborator add [project_id] user-can-write@example.com --write
 ```
 
 Alternatively, to give another user read access only (without the ability to upload to the project), run the following:
 ```sh
-g3t collaborator add user-read-only@example.com
+data-client collaborator add [project_id] user-read-only@example.com
 ```
 
 
 ## 2.  Approvals
-In order to implement these requests, **an authorized user will need to sign** the request before the user can use the remote repository. See `g3t collaborator approve --help
-`
+In order to implement these requests, **an authorized user will need to sign** the request before the user can use the remote repository. See `data-client collaborator approve --help`
diff --git a/docs/workflows/approve-requests.md → docs/calypr/calypr-admin/approve-requests.md b/docs/workflows/approve-requests.md → docs/calypr/calypr-admin/approve-requests.md
@@ -16,8 +16,8 @@
 * Ony users with the steward role can approve and sign a request
 
 ```text
-g3t collaborator approve --help
-Usage: g3t collaborator approve [OPTIONS]
+./data-client collaborator approve --help
+Usage: ./data-client collaborator approve [OPTIONS]
 
   Sign an existing request (privileged).
 
@@ -40,9 +40,9 @@ Note: This example uses the ohsu program, but the same process applies to all pr
 
 ```text
 ## As an admin, I need to grant data steward privileges add the requester reader and updater role on a program to an un-privileged user
-g3t collaborator add  add data_steward_example@<institution>.edu --resource_path /programs/<program_name>/projects  --steward
+./data-client collaborator add  add data_steward_example@<institution>.edu --resource_path /programs/<program_name>/projects  --steward
 # As an admin, approve that request
-g3t collaborator approve
+./data-client collaborator approve
 
 
 

diff --git a/docs/calypr/calypr-admin/creating-project.md b/docs/calypr/calypr-admin/creating-project.md
@@ -0,0 +1,48 @@
+---
+title: Creating a Project
+---
+
+## CLI
+
+```bash
+$ git drs init --help
+
+Usage: git drs init [OPTIONS] [PROJECT_ID]
+
+  Initialize a new repository.
+
+Options:
+  --debug        Enable debug mode. G3T_DEBUG environment variable can also be used.
+  --help         Show this message and exit.
+```
+
+## Overview
+The `git drs init` command initializes a new project in your current working directory. It works with existing files in the directory and creates a couple important directories:
+
+* `META/`: A visible directory within your project that houses the FHIR metadata files.
+* `CONFIG/`: Any additional configurations that can be used to customize the gen3 data platform. 
+
+An initialized project will look something like this...
+
+```
+.
+├── .git                                  // git repository state
+├── META                                  // metadata in FHIR format
+├── CONFIG
+└── <your data here>                      // existing data files maintained
+ └── ...
+```
+
+## Choosing a Project ID
+
+> In a Gen3 Data Commons, programs and projects are two administrative nodes in the graph database that serve as the most upstream nodes. A program must be created first, followed by a project. Any subsequent data submission and data access, along with control of access to data, is done through the project scope.
+> [more](https://gen3.org/resources/operator/#6-programs-and-projects)
+
+A project ID initializes a unique project, taking the form of program-project. A project ID is significant because it determines the location of the remote repository, bucket storage, and access control. Project IDs have a set of constraints, particularly the program name is predefined by the institution, while the project name must be unique within the server and alphanumeric without spaces. Contact an admin for a list of supported program names.
+
+### Authorization
+While you can work with an initialized repository locally, **an authorized user will need to sign** the project request before you can push your project to the data platform. You can confirm your project authorization with `git drs ping`
+
+## Next steps
+
+- [Adding data to a project](../calypr-projects/add-files.md)
diff --git a/docs/calypr/data-management/.nav.yml b/docs/calypr/data-management/.nav.yml
@@ -0,0 +1,6 @@
+nav:
+  - Git-DRS: git-drs.md
+  - Managing Metadata: meta-data.md
+  - Adding FHIR metadata: metadata.md
+  - Common Errors: common-errors.md
+
diff --git a/docs/calypr/data-management/common-errors.md b/docs/calypr/data-management/common-errors.md
@@ -0,0 +1,61 @@
+# Common Errors
+
+## .ndjson is out of date
+**Error:** After `git-drs` adding and committing a file, when you go to submit your data, "DocumentReference.ndjson is out of date",
+```sh
+$ git add file.txt
+$ git commit -m "adding file.txt"
+$ git push
+Please correct issues before pushing.
+Command `git drs status` failed with error code 1, stderr: WARNING: DocumentReference.ndjson is out of date 1969-12-31T16:00:00. The most recently changed file is MANIFEST/file.txt.dvc 2025-02-28T09:24:46.283870.  Please check DocumentReferences.ndjson
+No data file changes.
+```
+
+```
+$ forge meta init
+DocumentReference file not found at META/DocumentReference.ndjson. Creating a new one with new records.
+Processed 600 records
+Finished writing all DocumentReference records.
+Finished writing all Directory records.
+```
+
+To better understand the process of adding file metadata through the manifest, see [adding file metadata](add-files.md) and [adding FHIR metadata](metadata.md).
+
+## No new files to index
+
+**Error:**
+```sh
+$ git drs push
+No new files to index.  Use --overwrite to force
+```
+
+**Resolution:** When pushing data, `git-drs` checks the manifest (`MANIFEST/` directory) to see if there are any files to update, including new files or modified files. If no files have been modified, then the push will not go through. To push up the same file data or push up new FHIR metadata (`META/`), use `git drs push --overwrite`
+
+## Uncommitted changes
+
+**Error:** On the subsequent rounds of adding files, updating FHIR metadata, and committing the changes, you are unable to push up those new changes
+```
+$ git drs add hello.txt
+$ forge meta init
+$ git commit -m "add hello file"
+
+$ git drs push
+Uncommitted changes found.  Please commit or stash them first.
+
+$ git drs status
+No data file changes.
+On branch main
+Changes not staged for commit:
+ ...
+ modified:   META/DocumentReference.ndjson
+```
+
+**Resolution:** This happened because the update FHIR metadata created in the META init was not staged for commit. To stage and commit the FHIR metadata, do:
+
+```sh
+$ git add META/
+$ git commit -m "update DocumentReference.json"
+$ git drs push
+```
+
+Note that `git add` is used here rather than `git drs add` because `git add` will update the project's FHIR metadata while `git drs add` only updates the project's manifest. If you want to commit multiple file changes, you can also use `git commit -am "update all files"`, where all changes get committed to the project.