take a pass adding in marketing language

.python-version

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

AGENTS.md

@@ -0,0 +1,127 @@
+---
+lead: "This is a Zensical-based documentation site for calypr.org."
+personas:
+  - data-steward
+  - platform-engineer
+  - workflow-engineer
+solutions:
+  - manage-data
+  - manage-compute
+related_tools:
+  - git-drs
+  - syfon
+  - funnel
+  - data-client
+---
+
+# AGENTS.md — CALYPR Docs
+
+This is a Zensical-based documentation site for [calypr.org](https://calypr.org). The published site merges repo-authored docs with pages imported from upstream tool repos.
+
+## Architecture: Two-Stage Build
+
+**Never edit `.generated/` directly — it is a build artifact.**
+
+```
+docs/              ← repo-authored source (edit here)
+scripts/prepare_docs.py
+        ↓
+.generated/docs/   ← staged build input (Zensical reads this)
+        ↓
+zensical build
+        ↓
+site/              ← rendered output (build artifact)
+```
+
+- `docs/` is the only source of truth for repo-authored pages.
+- `git-drs` and `syfon` tool docs are imported from sibling repos (or GitHub fallback) into `.generated/docs/tools/`.
+- Import mappings live in `REPO_IMPORTS` inside `scripts/prepare_docs.py`.
+- `zensical.toml` is the **only** navigation source of truth — no `.nav.yml` files exist. An unregistered page will not appear in the nav.
+
+## Developer Workflows
+
+```bash
+# First-time setup
+python -m venv venv && source venv/bin/activate
+pip install -r requirements.txt   # installs: zensical, termynal
+
+# Local development loop
+make serve          # prepare .generated/docs + start live server
+make build          # prepare + one-shot build
+make prepare        # rebuild .generated/docs only
+
+# Maintenance
+make update-front-matter   # infer/update lead/personas/solutions/related_tools front matter
+make update-branches       # rewrite GitHub links to preferred upstream branches
+```
+
+Raw equivalents: `python scripts/prepare_docs.py` then `zensical serve`.
+
+## Front Matter Convention
+
+Every markdown file carries YAML front matter:
+
+```yaml
+---
+lead: "One-sentence description of this page."
+personas:
+  - data-steward
+  - platform-engineer
+solutions:
+  - manage-data
+related_tools:
+  - git-drs
+---
+```
+
+Run `python3 scripts/update_front_matter.py --check` in CI to verify front matter is up to date (exits non-zero if changes are needed). It is deterministic and idempotent.
+
+## Navigation Changes
+
+All nav edits go in `zensical.toml` under the `nav = [...]` array. Audience-based structure:
+- `Solutions` / `Products` → business-facing front
+- `Developers` → technical back; contains CALYPR Product Docs + Open Source Tool Docs
+
+## Adding Pages
+
+**Repo-authored page:** create under `docs/`, add entry to `zensical.toml`, run `make serve`.
+
+**Imported tool page:** add a `(source, dest)` tuple to `REPO_IMPORTS` in `scripts/prepare_docs.py`, register in `zensical.toml`, add link rewrites to `MARKDOWN_REWRITES` if needed, then run `make prepare && make build`.
+
+## Upstream Import Behavior
+
+By default the importer prefers local sibling repos (`../git-drs`, `../syfon`). Override with env vars:
+
+```bash
+CALYPR_IMPORT_PREFER_LOCAL=0                    # force remote fetch
+CALYPR_IMPORT_GIT_DRS_DIR=~/my-git-drs          # override local path
+CALYPR_IMPORT_SYFON_DIR=~/my-syfon
+```
+
+Branch preference order (from `scripts/branch_config.json`): `development → develop → main → master`.
+Last import decision is recorded in `.generated/imports.json`.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `zensical.toml` | Site config, **all navigation** |
+| `scripts/prepare_docs.py` | Stage docs + import tool repos (`REPO_IMPORTS`, `MARKDOWN_REWRITES`) |
+| `scripts/update_front_matter.py` | Infer/write front matter fields |
+| `scripts/update_doc_links.py` | Rewrite GitHub branch links |
+| `scripts/branch_config.json` | Branch preference order per repo |
+| `docs/stylesheets/extra.css` | Custom CSS |
+| `overrides/` | Zensical theme overrides |
+
+## Ignore These Directories
+
+`.generated/`, `site/`, `.cache/` — all build/runtime artifacts.
+
+## Known Warnings
+
+Zensical emits content warnings for bracketed literals from imported docs (`[SIGNED]`, `[]string`, `map[string]string`). These are benign rendering warnings, not build errors.
+
+## Deployment
+
+CI (GitHub Actions + Netlify) runs `python scripts/prepare_docs.py && zensical build --clean`. The import step must succeed — in CI, remote GitHub repos are used since local siblings are absent. Add `[skip ci]` to a commit message to skip the GitHub Actions build.
+

DEVELOPING.md

@@ -1,3 +1,25 @@
+---
+lead: "This repo now uses a Zensical-only build pipeline."
+personas:
+  - data-steward
+  - platform-engineer
+  - workflow-engineer
+  - researcher-bioinformatician
+  - standards-architecture-lead
+solutions:
+  - manage-data
+  - manage-compute
+  - integrate-data
+  - manage-models
+related_tools:
+  - git-drs
+  - syfon
+  - funnel
+  - forge
+  - grip
+  - sifter
+  - data-client
+---
 # Developing CALYPR Docs
 
 This repo now uses a Zensical-only build pipeline. MkDocs, `.nav.yml`, and the old multirepo plugin are gone.
@@ -49,6 +71,12 @@ zensical serve
 
 Navigation is fully defined in [zensical.toml](./zensical.toml).
 
+The current information architecture is intentionally audience-based:
+
+- `Home`, `Platform`, and `Solutions` are the business-facing front of the site.
+- `Developers` is the technical back of the site.
+- Existing CALYPR product docs and open-source tool docs keep their URLs, but they should not be treated as the main marketing entry point.
+
 If you want to:
 
 - rename a sidebar label
@@ -69,11 +97,16 @@ These live in `docs/` and should be edited directly there.
 Examples:
 
 - `docs/index.md`
+- `docs/platform/...`
+- `docs/solutions/...`
+- `docs/developers/index.md`
 - `docs/calypr/...`
 - `docs/tools/index.md`
 - `docs/tools/funnel/...`
 - `docs/tools/grip/...`
 
+Business-facing pages should explain outcomes first and link to developer docs second. Avoid making command references, protocol names, or implementation components the first thing a non-technical reader has to understand.
+
 ### Imported tool pages
 
 These are not authored in this repo anymore.

Makefile

@@ -1,17 +1,35 @@
 PYTHON ?= python3
 ZENSICAL ?= $(if $(wildcard ./venv/bin/zensical),./venv/bin/zensical,zensical)
 
+.PHONY: update-branches
+update-branches:
+	@echo "Updating GitHub branch links in docs..."
+	@$(PYTHON) scripts/update_doc_links.py
+
+.PHONY: update-front-matter
+update-front-matter:
+	@echo "Updating markdown front matter metadata..."
+	@$(PYTHON) scripts/update_front_matter.py
+
+.PHONY: prepare
+prepare: update-front-matter
+	@echo "Preparing documentation, adding meta for tools, personas, and solution links..."
+	@$(PYTHON) scripts/prepare_docs.py
+
 .PHONY: build
-build:
-	@$(ZENSICAL) build --clean
+build: prepare
+	@$(ZENSICAL) build
 
 .PHONY: serve
-serve:
+serve: prepare
 	@$(ZENSICAL) serve
 
 .PHONY: help
 help:
 	@echo "Makefile targets:"
+	@echo "  prepare           - Stage local docs plus imported upstream tool docs into .generated/docs"
 	@echo "  build             - Build the Zensical site with the active Python environment"
 	@echo "  serve             - Serve the Zensical site with the active Python environment"
-	@echo "  help              - Show this message"
+	@echo "  update-branches   - Update docs to point to configured development branches for repos"
+	@echo "  update-front-matter - Update markdown lead/personas/solutions/related_tools metadata"
+	@echo "  help              - Show this message"

README.md

@@ -1,3 +1,25 @@
+---
+lead: "This Zensical-based codebase deploys documentation to calypr.org."
+personas:
+  - data-steward
+  - platform-engineer
+  - workflow-engineer
+  - researcher-bioinformatician
+  - standards-architecture-lead
+solutions:
+  - manage-data
+  - manage-compute
+  - integrate-data
+  - manage-models
+related_tools:
+  - git-drs
+  - syfon
+  - funnel
+  - forge
+  - grip
+  - sifter
+  - data-client
+---
 # CALYPR Docs
 
 This Zensical-based codebase deploys documentation to [calypr.org](https://calypr.org).