diff --git a/.github/workflows/fr-gate-caller.yml b/.github/workflows/fr-gate-caller.yml deleted file mode 100644 index b725e2c..0000000 --- a/.github/workflows/fr-gate-caller.yml +++ /dev/null @@ -1,15 +0,0 @@ -name: FR gate - -# Per-repo caller. Blocks merges to staging/main/master unless every contained -# kanban item is in "Ready for staging" or "Ready for prod" respectively. -# All logic lives in tracebloc/.github/.github/workflows/fr-gate.yml. - -on: - pull_request: - branches: [staging, main, master] - types: [opened, reopened, synchronize, ready_for_review, labeled, unlabeled] - -jobs: - gate: - uses: tracebloc/.github/.github/workflows/fr-gate.yml@main - secrets: inherit diff --git a/.github/workflows/preview-page-coverage.yml b/.github/workflows/preview-page-coverage.yml new file mode 100644 index 0000000..1ca820d --- /dev/null +++ b/.github/workflows/preview-page-coverage.yml @@ -0,0 +1,154 @@ +name: Docs preview page coverage + +# Verifies that every page declared in docs.json's navigation is reachable +# (HTTP 200) on both the dev preview and prod docs site. +# +# Catches the failure mode from 2026-06-06: Mintlify's incremental builder +# left tracebloc-develop.mintlify.app with most pages returning 404 for days +# because the full-page index was wiped and only files touched by subsequent +# commits got re-rendered. Mintlify's own check reported "deploy success" +# every time. This workflow probes the actual rendered URLs and fails the +# build if any page is missing. +# +# Trigger: +# - schedule: daily 06:00 UTC (catches Mintlify state drift) +# - push: to develop / main (catches build regressions immediately) +# - workflow_dispatch: manual rerun +# +# After a push, waits 120s for Mintlify's deploy to complete before probing. + +on: + schedule: + - cron: '0 6 * * *' + push: + branches: [develop, main] + workflow_dispatch: + inputs: + env: + description: "Which environment to probe (default: both)" + type: choice + options: [both, dev, prod] + default: both + +permissions: + contents: read + +concurrency: + group: docs-coverage-${{ github.ref }} + cancel-in-progress: false + +jobs: + resolve-env: + runs-on: ubuntu-latest + outputs: + matrix: ${{ steps.set.outputs.matrix }} + steps: + - id: set + env: + CHOICE: ${{ github.event.inputs.env || 'both' }} + run: | + case "$CHOICE" in + dev) m='[{"name":"dev","url":"https://tracebloc-develop.mintlify.app"}]' ;; + prod) m='[{"name":"prod","url":"https://docs.tracebloc.io"}]' ;; + both|*) m='[{"name":"dev","url":"https://tracebloc-develop.mintlify.app"},{"name":"prod","url":"https://docs.tracebloc.io"}]' ;; + esac + echo "matrix=$m" >> "$GITHUB_OUTPUT" + + probe: + needs: resolve-env + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + env: ${{ fromJSON(needs.resolve-env.outputs.matrix) }} + steps: + - uses: actions/checkout@v4 + + - name: Wait for Mintlify to deploy (push events only) + if: github.event_name == 'push' + env: + ENV_NAME: ${{ matrix.env.name }} + run: | + # Mintlify's deploy typically completes in 30-90s after push. + # Allow a generous buffer so the probe sees the new state. + if [ "$ENV_NAME" = "prod" ] && [ "$GITHUB_REF_NAME" != "main" ]; then + echo "Push not to main — prod deploy won't run, skipping wait." + elif [ "$ENV_NAME" = "dev" ] && [ "$GITHUB_REF_NAME" != "develop" ]; then + echo "Push not to develop — dev deploy won't run, skipping wait." + else + echo "Waiting 120s for Mintlify ($ENV_NAME) deploy to complete..." + sleep 120 + fi + + - name: Extract every page path from docs.json + run: | + set -euo pipefail + # Walk the entire navigation tree and collect string-valued + # page references. docs.json nests pages under .navigation.tabs[] + # .groups[].pages[] (which can itself recurse). + jq -r ' + [.. | objects | .pages? | values | .[]?] + | map(select(type == "string")) + | unique + | .[] + ' docs.json > /tmp/pages.txt + count=$(wc -l < /tmp/pages.txt | tr -d ' ') + echo "Found $count pages to probe" + if [ "$count" = "0" ]; then + echo "::error::No pages found in docs.json — navigation structure may have changed" + exit 1 + fi + + - name: Probe each page on ${{ matrix.env.name }} + env: + BASE_URL: ${{ matrix.env.url }} + ENV_NAME: ${{ matrix.env.name }} + run: | + set -uo pipefail + : > /tmp/broken.csv + : > /tmp/ok.csv + while IFS= read -r path; do + [ -z "$path" ] && continue + # Follow redirects (-L); cap each request at 15s. + code=$(curl -s -L -o /dev/null -w "%{http_code}" --max-time 15 "$BASE_URL/$path" 2>/dev/null || echo "000") + if [ "$code" = "200" ]; then + echo "/$path,$code" >> /tmp/ok.csv + else + echo "/$path,$code" >> /tmp/broken.csv + echo " ✗ /$path -> HTTP $code" + fi + done < /tmp/pages.txt + + ok=$(wc -l < /tmp/ok.csv | tr -d ' ') + broken=$(wc -l < /tmp/broken.csv | tr -d ' ') + total=$((ok + broken)) + + echo "" + echo "═══ Result on $ENV_NAME: $ok/$total ok, $broken broken ═══" + + { + echo "## $ENV_NAME page coverage" + echo "" + echo "**$total pages probed · $ok ok · $broken broken**" + echo "" + echo "Base URL: \`$BASE_URL\`" + echo "" + if [ "$broken" -gt 0 ]; then + echo "### Broken paths" + echo "" + echo "| Path | HTTP code |" + echo "|---|---|" + awk -F, '{print "| `"$1"` | "$2" |"}' /tmp/broken.csv + echo "" + echo "**Likely cause:** Mintlify incremental builder did not re-render" + echo "these paths. Fix by touching every \`.mdx\` in one commit to" + echo "force a full rebuild (see PR #55 from 2026-06-06)." + else + echo "All pages render correctly. ✓" + fi + } >> "$GITHUB_STEP_SUMMARY" + + if [ "$broken" -gt 0 ]; then + echo "::error::$broken pages on $ENV_NAME returned non-200" + exit 1 + fi diff --git a/create-use-case/define.mdx b/create-use-case/define.mdx index 785ed54..0e46f04 100644 --- a/create-use-case/define.mdx +++ b/create-use-case/define.mdx @@ -255,3 +255,4 @@ Once models have been submitted, you can [compare them in the leaderboard sectio ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/create-use-case/evaluate-models.mdx b/create-use-case/evaluate-models.mdx index d2fd154..f700b89 100644 --- a/create-use-case/evaluate-models.mdx +++ b/create-use-case/evaluate-models.mdx @@ -49,3 +49,4 @@ Scores on the leaderboard are calculated using the metric you selected when defi ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/create-use-case/prepare-dataset.mdx b/create-use-case/prepare-dataset.mdx index aee27d7..872891c 100644 --- a/create-use-case/prepare-dataset.mdx +++ b/create-use-case/prepare-dataset.mdx @@ -597,3 +597,4 @@ kubectl get pvc -n ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/create-use-case/prerequisites.mdx b/create-use-case/prerequisites.mdx index eeb166a..cb9c8d9 100644 --- a/create-use-case/prerequisites.mdx +++ b/create-use-case/prerequisites.mdx @@ -275,3 +275,4 @@ This product is amazing! I love it. ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/create-use-case/templates.mdx b/create-use-case/templates.mdx index 72ac550..cf20000 100644 --- a/create-use-case/templates.mdx +++ b/create-use-case/templates.mdx @@ -35,3 +35,4 @@ For real examples already running on the platform, see the [explore section on t ## Need help? Email [support@tracebloc.io](mailto:support@tracebloc.io). + diff --git a/environment-setup/cli.mdx b/environment-setup/cli.mdx index ff83ae5..a463434 100644 --- a/environment-setup/cli.mdx +++ b/environment-setup/cli.mdx @@ -99,3 +99,4 @@ Both submit to the same ingestion protocol — pick the one that fits your workf ## Coming soon Cloud-source ingestion (S3 / GCS / HTTPS) for large datasets, a `dataset list` verb, and `semantic_segmentation` support. + diff --git a/environment-setup/configuration.mdx b/environment-setup/configuration.mdx index 6e2544b..ffd9a31 100644 --- a/environment-setup/configuration.mdx +++ b/environment-setup/configuration.mdx @@ -447,3 +447,4 @@ Tracebloc is designed so your data never has to leave your network. Here's how: - **Isolated.** Training runs in containers with restricted system access. Kubernetes namespaces separate workloads from each other. - **Scanned.** Submitted models are analyzed for vulnerabilities before execution on your infrastructure. - **Minimal footprint.** The installer only modifies `~/.tracebloc/` and Docker. No system-wide changes. + diff --git a/environment-setup/deploy-aks.mdx b/environment-setup/deploy-aks.mdx index d4b4041..bda4805 100644 --- a/environment-setup/deploy-aks.mdx +++ b/environment-setup/deploy-aks.mdx @@ -52,3 +52,4 @@ clusterScope: true - Use GPU node pools for training workloads; size requests/limits per job. - Day-2 upgrades and rollbacks: see [Operations](/environment-setup/operations). + diff --git a/environment-setup/deploy-bare-metal.mdx b/environment-setup/deploy-bare-metal.mdx index 222d1b9..37a63ab 100644 --- a/environment-setup/deploy-bare-metal.mdx +++ b/environment-setup/deploy-bare-metal.mdx @@ -56,3 +56,4 @@ clusterScope: true - Schedule MySQL and storage on reliable nodes; back up the data PVCs. - Size training compute per job via `RESOURCE_REQUESTS` / `RESOURCE_LIMITS` ([Configuration](/environment-setup/configuration#resource-limits-for-training-jobs)). - Day-2 upgrades and rollbacks: see [Operations](/environment-setup/operations). + diff --git a/environment-setup/deploy-local.mdx b/environment-setup/deploy-local.mdx index 2fa8e21..1d9f297 100644 --- a/environment-setup/deploy-local.mdx +++ b/environment-setup/deploy-local.mdx @@ -7,7 +7,7 @@ description: "Run a tracebloc workspace on a single machine — laptop or on-pre ## Prerequisites -- A machine: macOS, Linux, or Windows · 2 CPU · 4 GB RAM · 20 GB free disk. +- A machine: macOS, Linux, or Windows · 2 CPU · 5 GB RAM · 10 GB free disk to run (4 CPU · 16 GB · 50 GB to train on it). - Your **Client ID** and password from the [clients page](https://ai.tracebloc.io/clients). That's it — no Docker or Kubernetes knowledge needed. The installer sets up Docker and the cluster for you. @@ -53,3 +53,4 @@ GPUs are auto-detected on Linux (NVIDIA/AMD) — drivers, container toolkit, and - Your data persists in `HOST_DATA_DIR` across stop/start cycles (see [Operations](/environment-setup/operations)). - Need more headroom? Re-run the installer on a bigger machine, or add worker nodes with `AGENTS`. - For multi-node high availability, use [bare-metal](/environment-setup/deploy-bare-metal) or a managed cloud instead. + diff --git a/environment-setup/deploy-openshift.mdx b/environment-setup/deploy-openshift.mdx index e594f0c..15aa5d2 100644 --- a/environment-setup/deploy-openshift.mdx +++ b/environment-setup/deploy-openshift.mdx @@ -56,3 +56,4 @@ networkPolicy: - The bundled SCC grants the resource-monitor the host access it needs — review it against your cluster policy. - Size training compute per job; day-2 management is in [Operations](/environment-setup/operations). + diff --git a/environment-setup/deployment-environments.mdx b/environment-setup/deployment-environments.mdx index d3fc419..4298716 100644 --- a/environment-setup/deployment-environments.mdx +++ b/environment-setup/deployment-environments.mdx @@ -26,3 +26,4 @@ Each guide follows the same six headings, so you always know where to look: **When to pick it · Prerequisites · Install · Verify · Environment-specific config · Production notes.** Adding a new target later (GKE, on-prem k3s, …) means filling the same template. All environments deploy the same chart — see [Configuration](/environment-setup/configuration) for every value, and [Operations](/environment-setup/operations) for day-2 management. + diff --git a/environment-setup/eks-client-deployment-guide.mdx b/environment-setup/eks-client-deployment-guide.mdx index 2341c0c..dd4c07d 100644 --- a/environment-setup/eks-client-deployment-guide.mdx +++ b/environment-setup/eks-client-deployment-guide.mdx @@ -865,3 +865,4 @@ kubectl delete namespace - Email: [support@tracebloc.io](mailto:support@tracebloc.io) - Docs: [tracebloc Documentation Portal](https://docs.tracebloc.io) + diff --git a/environment-setup/operations.mdx b/environment-setup/operations.mdx index 3f57c13..28a6255 100644 --- a/environment-setup/operations.mdx +++ b/environment-setup/operations.mdx @@ -83,3 +83,4 @@ PVCs are annotated `helm.sh/resource-policy: keep`, so your data survives an uni ## Back up Your data lives in the data PVCs (or `~/.tracebloc` on a local install). Back up that directory / those volumes on your normal schedule — tracebloc keeps nothing of yours off your infrastructure. + diff --git a/environment-setup/overview.mdx b/environment-setup/overview.mdx index 1941f1a..674c82a 100644 --- a/environment-setup/overview.mdx +++ b/environment-setup/overview.mdx @@ -79,3 +79,4 @@ The installer changes only **Docker** and **`~/.tracebloc`** on your host — no Want the guarantees in detail for your security team? See [Security & data handling](/environment-setup/configuration#security). + diff --git a/environment-setup/quickstart.mdx b/environment-setup/quickstart.mdx index 333e179..0fb50f1 100644 --- a/environment-setup/quickstart.mdx +++ b/environment-setup/quickstart.mdx @@ -13,10 +13,10 @@ A running workspace in about 10 minutes, with one command. Deploying on a specif | You need | Minimum | |---|---| -| A machine | macOS, Linux, or Windows · 2 CPU · 4 GB RAM · 20 GB free disk | +| A machine | macOS, Linux, or Windows · 2 CPU · 5 GB RAM · 10 GB free disk | | A tracebloc account | [Sign up free](https://ai.tracebloc.io) — no credit card | -The installer runs below these too — it only warns, and more RAM mainly helps once models train. +That's enough to run a workspace. To **train on this machine**, give it 4 CPU · 16 GB RAM · 50 GB disk — a single training job alone reserves ~8 GB. The installer checks before it starts: below the minimum it stops on Linux (on macOS/Windows it warns — raise Docker Desktop's memory in Settings → Resources). @@ -79,3 +79,4 @@ If your security policy forbids piping scripts from the internet, skip the one-l Define a task and invite contributors. + diff --git a/environment-setup/security.mdx b/environment-setup/security.mdx index 4aacded..2e3992d 100644 --- a/environment-setup/security.mdx +++ b/environment-setup/security.mdx @@ -35,3 +35,4 @@ If support asks for diagnostics, `--diagnose` produces a bundle with **credentia ## Outbound access Your workspace needs outbound HTTPS to: `*.docker.io`, `ghcr.io`, `raw.githubusercontent.com`, `*.github.io`, `*.tracebloc.io`, and `pypi.org`. Nothing needs to reach *in*. + diff --git a/environment-setup/setup-guide.mdx b/environment-setup/setup-guide.mdx index a9eb9bb..72d764b 100644 --- a/environment-setup/setup-guide.mdx +++ b/environment-setup/setup-guide.mdx @@ -13,13 +13,13 @@ The installer deploys a **single-node workspace on one machine** — a local Kub ## Requirements -The installer runs on any modern machine (one host per workspace). These are the minimum specs to run a workspace comfortably: +The installer runs on any modern machine (one host per workspace) and **checks these before it starts** — below the minimum it stops on Linux with a clear message (on macOS/Windows it warns; raise Docker Desktop's memory in Settings → Resources). "To run" keeps a workspace online; **training on the same machine needs the headroom** — a single training job alone reserves ~8 GB. -| | Minimum | Recommended | +| | To run the workspace | To train on this machine | |---|---------|-------------| -| **CPU** | 2 cores | 8+ cores | -| **RAM** | 4 GB | 16+ GB | -| **Disk** | 20 GB free | 50+ GB free | +| **CPU** | 2 cores | 4+ cores | +| **RAM** | 5 GB | 16 GB | +| **Disk** | 10 GB free | 50+ GB free | **Supported platforms:** macOS (Intel & Apple Silicon) · Linux (x86_64 & arm64) · Windows (x86_64 & arm64) @@ -163,3 +163,4 @@ Your workspace is running. Here's where to go from here: **Data scientists:** [Join a use case](/join-use-case/join-use-case) — connect to a workspace, train models on real data, and submit results. **Advanced configuration:** [Configuration](/environment-setup/configuration) — customize installer options, manage the cluster, configure GPU settings, or deploy manually with Helm. + diff --git a/environment-setup/troubleshooting.mdx b/environment-setup/troubleshooting.mdx index f2fd0ce..efee42b 100644 --- a/environment-setup/troubleshooting.mdx +++ b/environment-setup/troubleshooting.mdx @@ -109,3 +109,4 @@ If training is slow, these are the factors to look at: - **Precision** — FP16/BF16 can speed up training 2-3x on modern GPUs - **Data pipeline** — slow CPU preprocessing (augmentation, tokenization) can bottleneck training - **Parallelization** — data parallelism splits batches across GPUs; model parallelism splits the model itself + diff --git a/join-use-case/explore-use-case.mdx b/join-use-case/explore-use-case.mdx index e20d23c..e8ebe1c 100644 --- a/join-use-case/explore-use-case.mdx +++ b/join-use-case/explore-use-case.mdx @@ -95,3 +95,4 @@ Learn how to [join a use case](/join-use-case/join-use-case) and get started wit ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/join-use-case/how-training-works.mdx b/join-use-case/how-training-works.mdx index ab0d252..44e1468 100644 --- a/join-use-case/how-training-works.mdx +++ b/join-use-case/how-training-works.mdx @@ -528,3 +528,4 @@ To validate a result you saw on the platform: If a number on your end doesn't line up with what the platform reports, please [contact us](mailto:support@tracebloc.io) so we can investigate together. + diff --git a/join-use-case/hyperparameters.mdx b/join-use-case/hyperparameters.mdx index 338511c..024130e 100644 --- a/join-use-case/hyperparameters.mdx +++ b/join-use-case/hyperparameters.mdx @@ -211,4 +211,4 @@ For more info about available functions and methods, call the help function in y user.help() ``` -- Email us at [support@tracebloc.io](mailto:support@tracebloc.io) \ No newline at end of file +- Email us at [support@tracebloc.io](mailto:support@tracebloc.io) diff --git a/join-use-case/join-use-case.mdx b/join-use-case/join-use-case.mdx index da9297c..e451e3c 100644 --- a/join-use-case/join-use-case.mdx +++ b/join-use-case/join-use-case.mdx @@ -35,3 +35,4 @@ To invite others to your team: ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/join-use-case/model-evaluation.mdx b/join-use-case/model-evaluation.mdx index 19c62f5..de5ae2b 100644 --- a/join-use-case/model-evaluation.mdx +++ b/join-use-case/model-evaluation.mdx @@ -37,3 +37,4 @@ Contributors are ranked by their best performing model score on the test data. C ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/join-use-case/model-optimization.mdx b/join-use-case/model-optimization.mdx index 2f986c0..56ecde7 100644 --- a/join-use-case/model-optimization.mdx +++ b/join-use-case/model-optimization.mdx @@ -348,3 +348,4 @@ The main file should contain the variable values as mentioned in type 2 format. ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/join-use-case/overview.mdx b/join-use-case/overview.mdx index c43dd85..cae5a74 100644 --- a/join-use-case/overview.mdx +++ b/join-use-case/overview.mdx @@ -53,3 +53,4 @@ Once training is complete, you select your best performing cycle and submit it f ## Need help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/join-use-case/start-training.mdx b/join-use-case/start-training.mdx index 63c22ac..7963246 100644 --- a/join-use-case/start-training.mdx +++ b/join-use-case/start-training.mdx @@ -244,4 +244,4 @@ For more info about available functions and methods, call the help function in y user.help() ``` -- Email us at [support@tracebloc.io](mailto:support@tracebloc.io) \ No newline at end of file +- Email us at [support@tracebloc.io](mailto:support@tracebloc.io) diff --git a/overview/tracebloc.mdx b/overview/tracebloc.mdx index bae2230..0e4fd97 100644 --- a/overview/tracebloc.mdx +++ b/overview/tracebloc.mdx @@ -119,4 +119,4 @@ tracebloc is a **collaborative AI workspace** you deploy on your own infrastruct GPU configuration, Helm deployment, EKS. - \ No newline at end of file + diff --git a/tools-help/faqs.mdx b/tools-help/faqs.mdx index de77be4..c2d3ce8 100644 --- a/tools-help/faqs.mdx +++ b/tools-help/faqs.mdx @@ -61,3 +61,4 @@ See the [pricing page](https://tracebloc.io/#pricing) on the website. - [Get started](/environment-setup/setup-guide) — install the client - [Browse key terms](/tools-help/key-terms) - [Use the Python SDK](/tools-help/tracebloc) + diff --git a/tools-help/key-terms.mdx b/tools-help/key-terms.mdx index 1cf8766..2c9ae6b 100644 --- a/tools-help/key-terms.mdx +++ b/tools-help/key-terms.mdx @@ -46,3 +46,4 @@ The process of adjusting a pre-trained model for a specific task. - [Check FAQs](/tools-help/faqs) - [Review SDK documentation](/tools-help/tracebloc) + diff --git a/tools-help/tracebloc.mdx b/tools-help/tracebloc.mdx index c3874f5..230879c 100644 --- a/tools-help/tracebloc.mdx +++ b/tools-help/tracebloc.mdx @@ -79,3 +79,4 @@ The fastest way to get started is our [Google Colab notebook](https://colab.rese - [Hyperparameters](/join-use-case/hyperparameters) — full reference for all training configuration options - [FAQs](/tools-help/faqs) - [Key terms](/tools-help/key-terms) +