diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..c689d68 --- /dev/null +++ b/.github/workflows/validate.yml @@ -0,0 +1,25 @@ +name: Documentation +on: + pull_request: + push: + branches: [main] +permissions: + contents: read +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version: 24 + cache: npm + - run: npm ci + - run: npm run validate + - run: npx playwright install --with-deps chromium + - run: npm run test:e2e + - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + if: failure() + with: + name: docs-browser-results + path: test-results/ diff --git a/.gitignore b/.gitignore index 37194ce..0ccc41b 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,10 @@ Thumbs.db # Mintlify .mintlify + +# Generated docs exports and browser results +public/llms.txt +public/llms-full.txt +test-results/ +playwright-report/ +.worktrees/ diff --git a/LICENSE-OPENSCIENCE b/LICENSE-OPENSCIENCE new file mode 100644 index 0000000..6e4da15 --- /dev/null +++ b/LICENSE-OPENSCIENCE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 InkVell Inc. (Synthetic Sciences) + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..49334ee --- /dev/null +++ b/NOTICE @@ -0,0 +1,10 @@ +OpenScience documentation + +The files in src/content/openscience are mirrored from +https://github.com/synthetic-sciences/openscience and retain their upstream +Apache License, Version 2.0. The exact revision is recorded in +scripts/openscience-source.json. See LICENSE-OPENSCIENCE for the license and NOTICE-OPENSCIENCE for the +upstream attribution notices. + +Scientific tool and skill catalogs link to their upstream source records; +those resources retain their respective authorship and license notices. diff --git a/NOTICE-OPENSCIENCE b/NOTICE-OPENSCIENCE new file mode 100644 index 0000000..05f34c2 --- /dev/null +++ b/NOTICE-OPENSCIENCE @@ -0,0 +1,154 @@ +OpenScience +Copyright 2026 Synthetic Sciences + +This product includes software developed at Synthetic Sciences. +Licensed under the Apache License, Version 2.0. + +It bundles or accesses the following third-party software and services. + +-------------------------------------------------------------------------------- +OpenCode +https://github.com/anomalyco/opencode · https://opencode.ai + +OpenScience is inspired by OpenCode and its work toward excellent open-source +agents. OpenScience applies that inspiration to making strong, open-source +scientific agents available to everyone. + +MIT License + +Copyright (c) 2025 opencode + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +-------------------------------------------------------------------------------- +Scientific Agent Skills (bundled scientific skills under backend/cli/skills/) +https://github.com/K-Dense-AI/scientific-agent-skills +Copyright (c) 2025 K-Dense Inc. +Licensed under the MIT License. See https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/LICENSE.md. + +166 of the bundled skills (biology, chemistry, databases, coding, data +engineering, physics, quantum, research, visualization and writing) are +derived from this collection, including skills taken from its earlier +scientific-skills/, scientific-databases/ and scientific-packages/ layout. +backend/cli/skills/ATTRIBUTION.md lists every one with its upstream path, and +each skill's frontmatter records the same under metadata.upstream. The +collection is described in Kassis, Agarwal, He, Patel and Brueckner, +"Scientific Agent Skills: A Library of Procedural Knowledge for Research +Agents", arXiv:2609.00065 (2026); cite it when these skills contribute to +published work. +-------------------------------------------------------------------------------- +Claude Scientific Writer (bundled skills under backend/cli/skills/) +https://github.com/K-Dense-AI/claude-scientific-writer +Copyright (c) 2025-2026 K-Dense Inc. +Licensed under the MIT License. + +The posters, slides, infographics and research-grants skills, and the style +references, review checklists and schematic scripts inside the core +paper-writing, ml-paper-writing, peer-review, hypotheses, literature-review, +schematics, citations, sources and brainstorming skills are derived from this +collection. See backend/cli/skills/ATTRIBUTION.md. +-------------------------------------------------------------------------------- +AI Research Skills (bundled ML skills under backend/cli/skills/) +https://github.com/Orchestra-Research/AI-Research-SKILLs +Copyright (c) 2025 Claude AI Research Skills Contributors (Orchestra Research) +Licensed under the MIT License. + +79 of the bundled skills (ml-training, ml-inference, llm-tools, cloud-compute +and related coding skills) are derived from this collection. See +backend/cli/skills/ATTRIBUTION.md. +-------------------------------------------------------------------------------- +Hugging Face skills (bundled hugging-face-* skills under backend/cli/skills/) +https://github.com/huggingface/skills +Copyright Hugging Face. +Licensed under the Apache License, Version 2.0. +-------------------------------------------------------------------------------- +Anthropic document skills (backend/cli/skills/document-parsing/{docx,pdf,pptx,xlsx}) +https://github.com/anthropics/skills +© 2025 Anthropic, PBC. All rights reserved. +Used under Anthropic's terms; each skill directory keeps Anthropic's LICENSE.txt. +Vendored through the K-Dense collections, which track the Anthropic originals. +-------------------------------------------------------------------------------- +NVIDIA BioNeMo Agent Toolkit (backend/cli/skills/biology/protein-binder-design) +https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit +Copyright NVIDIA Corporation. +Skills and documentation licensed under CC-BY-4.0; code under the Apache +License, Version 2.0; the models the workflow calls carry their own terms. +Pinned source revision: 0e67a612e4045f007e38fa77adc8f3ebfc5616b6. +-------------------------------------------------------------------------------- +pacsomatic (backend/cli/skills/biology/pacsomatic) +Copyright (c) 2026 Beifang Niu +Licensed under the MIT License. See the skill's LICENSE. +-------------------------------------------------------------------------------- +markitdown (bundled skill: backend/cli/skills/data-engineering/markitdown) +https://github.com/microsoft/markitdown +Copyright (c) Microsoft Corporation. +Licensed under the MIT License. See the skill's LICENSE.txt. +-------------------------------------------------------------------------------- +conducting-scientific-research and scientific-problem-selection bundled skills +https://github.com/Shoko-official/Claude-Science-System-Prompts +Copyright 2026 Shoko-official contributors. +Licensed under the Apache License, Version 2.0. +Pinned source revision: a55a1709d36534d42462b51f61f9859bf4ab23b6. +-------------------------------------------------------------------------------- +Iconoir icons (bundled in frontend/ui/src/components/iconoir-registry.ts) +https://github.com/iconoir-icons/iconoir + +MIT License + +Copyright (c) 2021 Luca Burgio + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +-------------------------------------------------------------------------------- + +Third-party scientific data sources +----------------------------------- +The scientific database connectors under backend/cli/src/science/connectors/ +access third-party public web APIs (including, among others, UniProt, RCSB PDB, +PDBe, AlphaFold DB, InterPro, Ensembl, NCBI E-utilities, ClinVar, gnomAD, UCSC, +ChEMBL, PubChem, ChEBI, Reactome, KEGG, STRING, IntAct, WikiPathways, +Open Targets, GEO, ArrayExpress, GTEx, the Human Protein Atlas, Europe PMC, +Crossref, OpenAlex, Semantic Scholar, arXiv, and bioRxiv). OpenScience does not +redistribute the data served by these APIs. Each source is governed by its own +terms of use and licensing; users are responsible for complying with the terms +of any data source they query. + +Client-side rendering libraries (Mol*, igv.js, RDKit.js, KaTeX, pdf.js, 3Dmol.js) +are dependencies declared in package.json and retain their own licenses. + +Fonts +----- +Computer Modern Unicode (CMU Concrete; frontend/landing/public/fonts, +frontend/workspace/public/fonts/cmc, frontend/docs/public/fonts/cmc) and Inter +(frontend/landing/public/fonts) are bundled under the SIL Open Font License 1.1; +the OFL text sits next to each font. diff --git a/README.md b/README.md index 7ecde15..11a440d 100644 --- a/README.md +++ b/README.md @@ -28,39 +28,60 @@ The source for [docs.syntheticsciences.ai](https://docs.syntheticsciences.ai). This repository is the whole docs site: a small Vite + React app that renders a folder of MDX pages. There is no docs framework, no CMS, and no server. Merges to `main` deploy automatically. -It documents two products: +It documents: -- **[OpenScience](https://docs.syntheticsciences.ai/#/openscience/index)**: the [open-source AI workbench](https://github.com/synthetic-sciences/openscience) for scientific research. Try it at [openscience.sh](https://openscience.sh). -- **[Atlas](https://docs.syntheticsciences.ai/#/atlas/index)**: the research graph. Hypotheses, runs, evidence, and decisions that outlive any one chat. Try it at [tryatlas.sh](https://tryatlas.sh). +- **[OpenScience](https://docs.syntheticsciences.ai/#/openscience/index)**: installation, models, Ace, research workflows, scientific tools, skills, and the local CLI/API. +- **[Synthetic Sciences](https://docs.syntheticsciences.ai/#/account/index)**: account access, workspaces, Wallet billing, usage, private Graphs, privacy, and Ascent access. + +Atlas is retired as a public website and package offer. The account compatibility guide explains retained identifiers; old Atlas documentation URLs redirect to current workflows. ## Development +Use Node.js 24 or later. Validation scripts import the same typed route helpers as the browser using Node's built-in TypeScript stripping. + ```bash -npm install -npm run dev # hot-reloads .mdx edits +npm ci +npm run dev +npm run validate +npx playwright install chromium +npm run test:e2e ``` -Before opening a PR: +Validation checks the OpenScience mirror, every page and heading link, navigation and redirects, TypeScript, route behavior, and a production build. Browser tests visit every page and exercise search, anchors, legacy URLs, mobile navigation, copy, and plain-text exports. CI runs both gates on pull requests. + +## Update OpenScience content + +The canonical source is `frontend/docs/src/content/openscience` in [synthetic-sciences/openscience](https://github.com/synthetic-sciences/openscience). Edit and validate there first, then commit the source and sync it here: ```bash -npm run validate # link check plus a production build +npm run sync:openscience -- --source /path/to/openscience +npm run sync:openscience -- --source /path/to/openscience --check +npm run validate ``` -## Adding a page +The script copies every page and navigation file without rewriting content, removes obsolete mirror pages, and records the exact source revision and SHA-256 file hashes in `scripts/openscience-source.json`. It refuses uncommitted canonical content. CI rejects mirror drift. OpenScience behavior and schema examples are validated in the canonical repository; this site verifies the mirrored content and its rendering. + +## Update account content + +Create or edit `src/content/account/.mdx` with quoted `title` and `description` frontmatter, then add it to `src/content/account/docs.json`. Check behavior against the current `synthetic-sciences/atlas` repository, especially its product-boundary instructions and server authorization. See [the source map](docs/content-map.md). + +Use `/openscience/` or `/account/` internal links, optionally followed by `#`. Same-page anchors use `#`. Both second- and third-level headings have targets. The renderer accepts Markdown and the existing Card/Columns components; arbitrary MDX is not compiled. + +Routing uses `#/
/#`. `src/navigation.ts` owns current routes and old Atlas, agent-cli, and stored-product redirects. Unknown pages show a recoverable not-found view. `npm run check-links` validates links, anchors, page coverage, and redirect targets using that same implementation. -1. Create `src/content/
/.mdx` with `title` and `description` frontmatter. -2. Add the page to that section's `docs.json` under the right group. -3. Run `npm run check-links` to confirm the nav and every internal link resolve. +## Exports and deployment -Each section lives in `src/content/
/` as `.mdx` pages plus a `docs.json` for the sidebar. Routing is hash-based (`#/
/`), and URLs from older layouts redirect through the alias maps in `src/DocsApp.tsx`, so old links keep working. +Builds generate `public/llms.txt` and `public/llms-full.txt` from every navigation page. These are ignored by Git and included in `dist/`. Merges to `main` deploy through the existing hosting integration; check its deployment status before reporting the live site updated. -## Style guide +## Style and scope -- Copy says "Atlas", "OpenScience", or "Synthetic Sciences". No internal vendor names. -- OpenScience docs present bring-your-own-key as the default; Atlas is optional, never required. -- Use canonical singular command names. Installs always use `@latest`. -- Active voice, second person, sentence case headings. +- Use current product names: OpenScience and Synthetic Sciences. Atlas appears only in compatibility guidance. +- First-run OpenScience setup requires an account. Ace is optional; direct provider and local routes remain direct. +- Separate purchased Wallet funds, expiring promotional credit, managed usage, provider estimates, and card receipts. +- Enabling Ace access costs $0. Auto reload is separate consent for fixed $20 funding below $5, plus the disclosed processing fee. +- Describe supported user actions with exact labels, prerequisites, outcomes, and recovery steps. Do not advertise retained code as an active product. +- Use active voice, second person, sentence case headings, labelled code fences, and examples without real secrets. ## License -MIT for this site; see [LICENSE](LICENSE). The products keep their own licenses (OpenScience is Apache-2.0). +MIT for the site code and account guides; see [LICENSE](LICENSE). Mirrored OpenScience documentation retains its upstream Apache-2.0 license; see [NOTICE](NOTICE) and [LICENSE-OPENSCIENCE](LICENSE-OPENSCIENCE). diff --git a/docs/content-map.md b/docs/content-map.md new file mode 100644 index 0000000..8230112 --- /dev/null +++ b/docs/content-map.md @@ -0,0 +1,31 @@ +# Documentation source map + +Audit baseline: OpenScience `3b587c253`, account service `8961df0a` (September 26, 2026). The exact mirrored OpenScience revision and file hashes are recorded in `scripts/openscience-source.json` after synchronization. + +## OpenScience + +All guides, the scientific database catalog, scientific capability catalog, and bundled skill directory mirror the canonical repository. Its `docs/notes/documentation-map.md` maps pages to implementation and verification. Run its `test:docs`, documentation typecheck/build, and Playwright suite before syncing. + +## Account and Graphs + +Source paths below are relative to `synthetic-sciences/atlas`. + +| Pages | Implementation and behavior | +| --- | --- | +| `index`, `quickstart`, `compatibility` | `AGENTS.md`, `frontend/src/App.tsx`, `backend/app/main.py`: current surfaces, retired product offers, mounted versus retained routes. | +| `authentication`, `api-keys` | `frontend/src/components/organizations/WorkspaceApiKeysSection.tsx`, `backend/app/routes/auth.py`, `backend/app/routes/organizations.py`; OpenScience `src/cli/cmd/connect.ts`: one-time secrets, pinned workspace, revocation, device versus pasted-key logout. | +| `workspaces` | `OrganizationShell.tsx`, `OrganizationMembersSection.tsx`, `OrganizationSettingsPage.tsx` under `frontend/src/components/organizations/`; `backend/app/services/organization_service.py`: membership, permissions, separate ownership transfer, member spend limits. | +| `shared-connections` | `OrganizationSharedCredentialsPage.tsx`, `frontend/src/components/pages/CliPage.tsx`, `backend/app/services/workspace_provider_credential_service.py`: shared scope and permission gates. | +| `billing` | `OrganizationBillingPage.tsx`, `OrganizationAcePage.tsx`, `backend/app/services/organization_auto_reload_service.py`, `ace_pricing_service.py`, `docs/ACE_PROVIDER_PRICING.md`: prepaid/promo access, fixed optional reloads, separate limits, direct versus OpenRouter fees. | +| `usage` | `frontend/src/components/pages/UsagePage.tsx`, `OrganizationUsagePage.tsx`, `frontend/src/components/billing/UsageBreakdown.tsx`, `usage-data.ts`, `backend/app/routes/credits.py`: inclusive UTC dates, 366 days, aggregate CSV, permissions, reported versus estimated usage. | +| `privacy` | OpenScience `frontend/workspace/src/components/settings/General.tsx`; `backend/app/routes/telemetry.py`: device and account consent, deletion scope, redaction, traces versus billing records. | +| `graphs`, `evidence`, `sharing` | `frontend/src/components/node/`, `frontend/src/components/export/`, `backend/app/models/node.py`, `backend/app/routes/nodes.py`, `sharing.py`, `export_import.py`: staged records, commit gates, revisions, explicit sharing, export scope. | +| `ascent` | `frontend/src/components/pages/AscentPage.tsx`, `backend/app/routes/ascent.py`: request, pending/approved/denied states, protected download, entitlement independent of Wallet. | +| `api` | Mounted routes in `backend/app/main.py` and their route modules; no blanket promise that legacy CLI routes are public or accept model-access keys. | +| `troubleshooting` | The sources above and their current error/recovery controls. | + +## Maintaining coverage + +Update the relevant page when a user action, default, permission, cost, or recovery path changes. Keep operational infrastructure and financial repair procedures in the account repository. Do not publish private source links as setup prerequisites. Verify actual account UI and request contracts before changing financial or access statements. + +Run validation, browser checks, and mirror verification before merging. The browser suite visits every page, verifies all second/third-level anchors, checks responsive overflow, and tests old links, search, exports, copy, and unknown routes. diff --git a/e2e/docs.spec.ts b/e2e/docs.spec.ts new file mode 100644 index 0000000..4b010be --- /dev/null +++ b/e2e/docs.spec.ts @@ -0,0 +1,112 @@ +import { expect, test } from "@playwright/test"; +import { readFileSync } from "node:fs"; +import { aliases, atlasAliases, headings, slug } from "../src/navigation"; + +const sections = ["openscience", "account"]; +const pages = sections.flatMap((section) => { + const config = JSON.parse(readFileSync(new URL(`../src/content/${section}/docs.json`, import.meta.url), "utf8")) as { + navigation: { tabs: { groups: { pages: string[] }[] }[] }; + }; + return config.navigation.tabs.flatMap((tab) => tab.groups.flatMap((group) => group.pages.map((path) => ({ section, path })))); +}); + +test("every page renders with metadata, real anchors, and no viewport overflow", async ({ page }) => { + const errors: string[] = []; + page.on("pageerror", (error) => errors.push(error.message)); + for (const item of pages) { + const source = readFileSync(new URL(`../src/content/${item.section}/${item.path}.mdx`, import.meta.url), "utf8"); + const title = source.match(/^title: "(.+)"$/m)![1]; + await page.goto(`#/${item.section}/${item.path}`); + await expect(page.getByRole("heading", { level: 1 })).toHaveText(title); + await expect(page).toHaveTitle(title + " · Synthetic Sciences Docs"); + for (const heading of headings(source, 3)) await expect(page.locator(`[id="${slug(heading)}"]`)).toHaveCount(1); + expect(await page.evaluate(() => document.documentElement.scrollWidth > window.innerWidth), `${item.section}/${item.path}`).toBe(false); + } + expect(errors).toEqual([]); +}); + +test("section links retain their page through refresh and browser history", async ({ page }) => { + await page.goto("#/account/billing"); + await page.getByRole("complementary", { name: "on this page" }).getByRole("link", { name: "Optional auto reload" }).click(); + await expect(page).toHaveURL(/account\/billing#optional-auto-reload$/); + await expect(page.getByRole("heading", { name: "Optional auto reload", exact: true })).toBeInViewport(); + await page.reload(); + await expect(page.getByRole("heading", { name: "Optional auto reload", exact: true })).toBeInViewport(); + await page.getByRole("link", { name: "Usage reports", exact: true }).first().click(); + await page.goBack(); + await expect(page).toHaveURL(/account\/billing#optional-auto-reload$/); + await page.goto("#/openscience/tool-catalog#rdkit"); + await expect(page.getByRole("heading", { name: "RDKit", exact: true })).toBeInViewport(); +}); + +test("all legacy guides redirect and unknown routes remain recoverable", async ({ page }) => { + for (const [old, target] of Object.entries(atlasAliases)) { + await page.goto(`#/atlas/${old}`); + await expect(page).toHaveURL(new RegExp(`/${target.section}/${target.path}$`)); + await expect(page.getByRole("heading", { level: 1 })).not.toHaveText("Page not found"); + } + for (const [old, path] of Object.entries(aliases)) { + await page.goto(`#/openscience/${old}`); + await expect(page).toHaveURL(new RegExp(`/openscience/${path}$`)); + } + await page.goto("#/account/missing"); + await expect(page.getByRole("heading", { level: 1 })).toHaveText("Page not found"); + await page.goto("#/openscience/%E0%A4%A"); + await expect(page.getByRole("heading", { level: 1 })).toHaveText("Page not found"); +}); + +test("keyboard search works across account and workbench guides", async ({ page }) => { + await page.goto("#/openscience/index"); + const search = page.getByRole("combobox", { name: "Search documentation" }); + await search.fill("Ascent access"); + await search.press("ArrowDown"); + await search.press("ArrowUp"); + await search.press("Enter"); + await expect(page.getByRole("heading", { level: 1 })).toHaveText("Ascent access"); + await search.fill("no-results-for-this-query"); + await expect(page.getByText("No docs match that query.")).toBeVisible(); + await search.press("Escape"); + await expect(page.getByRole("listbox")).toHaveCount(0); +}); + +test("mobile search, collapsible navigation, and catalog tables remain usable", async ({ page }) => { + await page.setViewportSize({ width: 390, height: 844 }); + await page.goto("#/account/index"); + await expect(page.getByRole("combobox", { name: "Search documentation" })).toBeVisible(); + const menu = page.getByRole("button", { name: "Browse documentation" }); + await expect(menu).toHaveAttribute("aria-expanded", "false"); + await menu.click(); + await page.getByRole("complementary", { name: "documentation navigation" }).getByRole("link", { name: "Wallet and billing", exact: true }).click(); + await expect(menu).toHaveAttribute("aria-expanded", "false"); + await expect(page.getByRole("heading", { level: 1 })).toHaveText("Wallet and billing"); + for (const route of ["account/billing", "openscience/ace-models", "openscience/tool-catalog", "openscience/skill-library"]) { + await page.goto(`#/${route}`); + expect(await page.evaluate(() => document.documentElement.scrollWidth > window.innerWidth), route).toBe(false); + } + await page.goto("#/account/billing#optional-auto-reload"); + await expect(page.getByRole("heading", { name: "Optional auto reload", exact: true })).toBeInViewport(); + const nav = await page.getByRole("navigation", { name: "product sections" }).boundingBox(); + const header = await page.getByRole("banner").boundingBox(); + expect(nav!.y).toBeGreaterThanOrEqual(Math.max(0, header!.y + header!.height)); + await page.goto("#/account/billing"); + await expect(page.getByRole("heading", { level: 1 })).toHaveText("Wallet and billing"); + await expect(page.getByRole("button", { name: /Account & Graphs/ })).toHaveAttribute("aria-current", "page"); + await page.screenshot({ path: "test-results/account-mobile.png", fullPage: false, animations: "disabled" }); +}); + +test("copy and generated exports include current content", async ({ page, context }) => { + await context.grantPermissions(["clipboard-read", "clipboard-write"]); + await page.goto("#/openscience/quickstart"); + await page.getByRole("button", { name: "copy code", exact: true }).first().click(); + await expect(page.getByRole("button", { name: "copy code", exact: true }).first()).toContainText("copied"); + expect(await page.evaluate(() => navigator.clipboard.readText())).toContain("@synsci/openscience@latest"); + for (const name of ["llms.txt", "llms-full.txt"]) { + const response = await page.request.get(name); + expect(response.ok()).toBe(true); + const body = await response.text(); + expect(body).toContain("Ace model directory"); + expect(body).toContain("Atlas compatibility and migration"); + } + await page.goto("#/account/index"); + await page.screenshot({ path: "test-results/account-desktop.png", fullPage: false, animations: "disabled" }); +}); diff --git a/index.html b/index.html index 056e42a..7837a88 100644 --- a/index.html +++ b/index.html @@ -3,6 +3,7 @@ + Synthetic Sciences Docs diff --git a/package-lock.json b/package-lock.json index f2a46be..43d860b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -16,21 +16,25 @@ "remark-gfm": "^4.0.0" }, "devDependencies": { + "@playwright/test": "1.63.0", "@types/react": "^19.0.0", "@types/react-dom": "^19.0.0", "@vitejs/plugin-react": "^4.3.4", "typescript": "^5.6.3", "vite": "^6.0.5" + }, + "engines": { + "node": ">=24" } }, "node_modules/@babel/code-frame": { - "version": "7.29.0", - "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.0.tgz", - "integrity": "sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.7.tgz", + "integrity": "sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==", "dev": true, "license": "MIT", "dependencies": { - "@babel/helper-validator-identifier": "^7.28.5", + "@babel/helper-validator-identifier": "^7.29.7", "js-tokens": "^4.0.0", "picocolors": "^1.1.1" }, @@ -39,9 +43,9 @@ } }, "node_modules/@babel/compat-data": { - "version": "7.29.3", - "resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.3.tgz", - "integrity": "sha512-LIVqM46zQWZhj17qA8wb4nW/ixr2y1Nw+r1etiAWgRM6U1IqP+LNhL1yg440jYZR72jCWcWbLWzIosH+uP1fqg==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.7.tgz", + "integrity": "sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg==", "dev": true, "license": "MIT", "engines": { @@ -49,21 +53,21 @@ } }, "node_modules/@babel/core": { - "version": "7.29.0", - "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.0.tgz", - "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.7.tgz", + "integrity": "sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA==", "dev": true, "license": "MIT", "dependencies": { - "@babel/code-frame": "^7.29.0", - "@babel/generator": "^7.29.0", - "@babel/helper-compilation-targets": "^7.28.6", - "@babel/helper-module-transforms": "^7.28.6", - "@babel/helpers": "^7.28.6", - "@babel/parser": "^7.29.0", - "@babel/template": "^7.28.6", - "@babel/traverse": "^7.29.0", - "@babel/types": "^7.29.0", + "@babel/code-frame": "^7.29.7", + "@babel/generator": "^7.29.7", + "@babel/helper-compilation-targets": "^7.29.7", + "@babel/helper-module-transforms": "^7.29.7", + "@babel/helpers": "^7.29.7", + "@babel/parser": "^7.29.7", + "@babel/template": "^7.29.7", + "@babel/traverse": "^7.29.7", + "@babel/types": "^7.29.7", "@jridgewell/remapping": "^2.3.5", "convert-source-map": "^2.0.0", "debug": "^4.1.0", @@ -80,14 +84,14 @@ } }, "node_modules/@babel/generator": { - "version": "7.29.1", - "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.29.1.tgz", - "integrity": "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==", + "version": "7.29.8", + "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.29.8.tgz", + "integrity": "sha512-gZbepsdh3WDtgZKWL+vTPh71LSBrm/Y4/QDZBVCcYfmeTEEuoOYwlSy+G1StfJg+/Zy550u/3TATbm7qDbbMtg==", "dev": true, "license": "MIT", "dependencies": { - "@babel/parser": "^7.29.0", - "@babel/types": "^7.29.0", + "@babel/parser": "^7.29.8", + "@babel/types": "^7.29.8", "@jridgewell/gen-mapping": "^0.3.12", "@jridgewell/trace-mapping": "^0.3.28", "jsesc": "^3.0.2" @@ -97,14 +101,14 @@ } }, "node_modules/@babel/helper-compilation-targets": { - "version": "7.28.6", - "resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.28.6.tgz", - "integrity": "sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.29.7.tgz", + "integrity": "sha512-wem6WaBj4NaVYVdNhLPPVacES6ZJ+KBBfSkTMD3YZxbP3rm3Di85tJU5ljaUNhaOynt+Aj0xruhYuzQBt8n71g==", "dev": true, "license": "MIT", "dependencies": { - "@babel/compat-data": "^7.28.6", - "@babel/helper-validator-option": "^7.27.1", + "@babel/compat-data": "^7.29.7", + "@babel/helper-validator-option": "^7.29.7", "browserslist": "^4.24.0", "lru-cache": "^5.1.1", "semver": "^6.3.1" @@ -114,9 +118,9 @@ } }, "node_modules/@babel/helper-globals": { - "version": "7.28.0", - "resolved": "https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.28.0.tgz", - "integrity": "sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.29.7.tgz", + "integrity": "sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==", "dev": true, "license": "MIT", "engines": { @@ -124,29 +128,29 @@ } }, "node_modules/@babel/helper-module-imports": { - "version": "7.28.6", - "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.28.6.tgz", - "integrity": "sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.29.7.tgz", + "integrity": "sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==", "dev": true, "license": "MIT", "dependencies": { - "@babel/traverse": "^7.28.6", - "@babel/types": "^7.28.6" + "@babel/traverse": "^7.29.7", + "@babel/types": "^7.29.7" }, "engines": { "node": ">=6.9.0" } }, "node_modules/@babel/helper-module-transforms": { - "version": "7.28.6", - "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.28.6.tgz", - "integrity": "sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.29.7.tgz", + "integrity": "sha512-UPUVSyXbOh627KiCIGQSgwWzGeBKLkaJ9PJEdrngIwMSzxLR4jS4+f1f1jb7VzBbg8nFLaYotvVPFCTqdrmTAg==", "dev": true, "license": "MIT", "dependencies": { - "@babel/helper-module-imports": "^7.28.6", - "@babel/helper-validator-identifier": "^7.28.5", - "@babel/traverse": "^7.28.6" + "@babel/helper-module-imports": "^7.29.7", + "@babel/helper-validator-identifier": "^7.29.7", + "@babel/traverse": "^7.29.7" }, "engines": { "node": ">=6.9.0" @@ -166,9 +170,9 @@ } }, "node_modules/@babel/helper-string-parser": { - "version": "7.27.1", - "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz", - "integrity": "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.7.tgz", + "integrity": "sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==", "dev": true, "license": "MIT", "engines": { @@ -176,9 +180,9 @@ } }, "node_modules/@babel/helper-validator-identifier": { - "version": "7.28.5", - "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz", - "integrity": "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz", + "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==", "dev": true, "license": "MIT", "engines": { @@ -186,9 +190,9 @@ } }, "node_modules/@babel/helper-validator-option": { - "version": "7.27.1", - "resolved": "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-7.27.1.tgz", - "integrity": "sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-7.29.7.tgz", + "integrity": "sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==", "dev": true, "license": "MIT", "engines": { @@ -196,27 +200,27 @@ } }, "node_modules/@babel/helpers": { - "version": "7.29.2", - "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.29.2.tgz", - "integrity": "sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.29.7.tgz", + "integrity": "sha512-1k2lAGRMfHTcwuNYcCNUmaUffmQv8KWMfh2iJUUeRlwlwH4FdNG7mfPI10NPfLHJFThE4Tyr4mv7kTNZOiPuBg==", "dev": true, "license": "MIT", "dependencies": { - "@babel/template": "^7.28.6", - "@babel/types": "^7.29.0" + "@babel/template": "^7.29.7", + "@babel/types": "^7.29.7" }, "engines": { "node": ">=6.9.0" } }, "node_modules/@babel/parser": { - "version": "7.29.3", - "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.3.tgz", - "integrity": "sha512-b3ctpQwp+PROvU/cttc4OYl4MzfJUWy6FZg+PMXfzmt/+39iHVF0sDfqay8TQM3JA2EUOyKcFZt75jWriQijsA==", + "version": "7.29.9", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.9.tgz", + "integrity": "sha512-CjXrNHTnvqBVqHgdBysY3vk2T8tpJHb5/RMeHJBTyVa9xgugCB0CJTx/3oO8RV2QRQP391RWpB7D6hLjm8V9uA==", "dev": true, "license": "MIT", "dependencies": { - "@babel/types": "^7.29.0" + "@babel/types": "^7.29.8" }, "bin": { "parser": "bin/babel-parser.js" @@ -258,33 +262,33 @@ } }, "node_modules/@babel/template": { - "version": "7.28.6", - "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.28.6.tgz", - "integrity": "sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==", + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.29.7.tgz", + "integrity": "sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==", "dev": true, "license": "MIT", "dependencies": { - "@babel/code-frame": "^7.28.6", - "@babel/parser": "^7.28.6", - "@babel/types": "^7.28.6" + "@babel/code-frame": "^7.29.7", + "@babel/parser": "^7.29.7", + "@babel/types": "^7.29.7" }, "engines": { "node": ">=6.9.0" } }, "node_modules/@babel/traverse": { - "version": "7.29.0", - "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.0.tgz", - "integrity": "sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==", + "version": "7.29.8", + "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.8.tgz", + "integrity": "sha512-I5z7H3bf/41ktsNVLtpN0wAa336HkqIHQ5BuPLEhTkt1jVSyZpeNKIzTgEWmlxjdg81R0IgUCcaE+Ok3NvrfZg==", "dev": true, "license": "MIT", "dependencies": { - "@babel/code-frame": "^7.29.0", - "@babel/generator": "^7.29.0", - "@babel/helper-globals": "^7.28.0", - "@babel/parser": "^7.29.0", - "@babel/template": "^7.28.6", - "@babel/types": "^7.29.0", + "@babel/code-frame": "^7.29.7", + "@babel/generator": "^7.29.8", + "@babel/helper-globals": "^7.29.7", + "@babel/parser": "^7.29.8", + "@babel/template": "^7.29.7", + "@babel/types": "^7.29.8", "debug": "^4.3.1" }, "engines": { @@ -292,14 +296,14 @@ } }, "node_modules/@babel/types": { - "version": "7.29.0", - "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.0.tgz", - "integrity": "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==", + "version": "7.29.8", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.8.tgz", + "integrity": "sha512-Vj1jF3cPfxg7OAfoI7QnVKLoILlm2JF9pnVHrX8qx7AHMiYWT+NDAA7jChlNgRS4WTLc/fD1lXLmPixluj+3Gg==", "dev": true, "license": "MIT", "dependencies": { - "@babel/helper-string-parser": "^7.27.1", - "@babel/helper-validator-identifier": "^7.28.5" + "@babel/helper-string-parser": "^7.29.7", + "@babel/helper-validator-identifier": "^7.29.7" }, "engines": { "node": ">=6.9.0" @@ -797,6 +801,22 @@ "@jridgewell/sourcemap-codec": "^1.4.14" } }, + "node_modules/@playwright/test": { + "version": "1.63.0", + "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.63.0.tgz", + "integrity": "sha512-oxMK4vllB9RK5NQ2l1pq1IfOf2AvnEuj/vYGDj0H2nMtmtZpKtCwt/l00GEO6xjGfpBNAvjovvYdCm50dRQkpQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "playwright": "1.63.0" + }, + "bin": { + "playwright": "cli.js" + }, + "engines": { + "node": ">=20" + } + }, "node_modules/@rolldown/pluginutils": { "version": "1.0.0-beta.27", "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz", @@ -1310,9 +1330,9 @@ } }, "node_modules/baseline-browser-mapping": { - "version": "2.10.31", - "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.31.tgz", - "integrity": "sha512-MujYO3eP72uvmSE0i4wltsodRfIpZATP3jvzRNRGGxgzId7aVocVJJV3nf01qnzzKFGxQVC9bpWxl5cjxTr/7Q==", + "version": "2.11.26", + "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.26.tgz", + "integrity": "sha512-GLQdD3y6UF8iVuMJl5fHgE4jdn/ua7n+toKfLgNlg3BqQtOZjpy68T8Tup8/wGWZCDlm7KMg7tPb4MPn7oN0TQ==", "dev": true, "license": "Apache-2.0", "bin": { @@ -1323,9 +1343,9 @@ } }, "node_modules/browserslist": { - "version": "4.28.2", - "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.2.tgz", - "integrity": "sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==", + "version": "4.29.1", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.29.1.tgz", + "integrity": "sha512-AUdjuRyCNGUYtqpqfTmWyM4fXay8yIQhmLnvYe/THMGfT9B/34X7xQd3ifKxwyNPPpowVBjLb+64BN9Rn1mizw==", "dev": true, "funding": [ { @@ -1343,11 +1363,11 @@ ], "license": "MIT", "dependencies": { - "baseline-browser-mapping": "^2.10.12", - "caniuse-lite": "^1.0.30001782", - "electron-to-chromium": "^1.5.328", - "node-releases": "^2.0.36", - "update-browserslist-db": "^1.2.3" + "baseline-browser-mapping": "^2.11.25", + "caniuse-lite": "^1.0.30001810", + "electron-to-chromium": "^1.5.438", + "node-releases": "^2.0.57", + "update-browserslist-db": "^1.3.3" }, "bin": { "browserslist": "cli.js" @@ -1357,9 +1377,9 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001793", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001793.tgz", - "integrity": "sha512-iwSsYWaCOoh26cV8NwNRViHlrfUvYsHDfRVcbtmw0Kg6PJIZZXwMkj1442FYLBGkeUf1juAsU3DTfxW579mrPA==", + "version": "1.0.30001812", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001812.tgz", + "integrity": "sha512-qN+QNNBr93TCmFrmte0bBCjSDMuRvt78VlHT99qIGPszm4QsqCX8lnyWUFkHi8B7ZBAPq8SH+UqyXNy/odMdng==", "dev": true, "funding": [ { @@ -1503,9 +1523,9 @@ } }, "node_modules/electron-to-chromium": { - "version": "1.5.361", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.361.tgz", - "integrity": "sha512-Q6Hts7N9FnJc5LeGRINFvLhCI9xZmNtTDe5ZbcVezQz7cU4a8Aua3GH1b8J2XY8Al9PF+OCwYqhgsOOheMdvkA==", + "version": "1.5.439", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.439.tgz", + "integrity": "sha512-qu6QIPXhsb+CRcAiTMNjR4A1y/7tCYKkKjr5CZXRVih6qkDf79peZ2BpEU3qoDBNCRrcy3Mra3X9nG5oruuA7Q==", "dev": true, "license": "ISC" }, @@ -2656,9 +2676,9 @@ "license": "MIT" }, "node_modules/nanoid": { - "version": "3.3.12", - "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz", - "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==", + "version": "3.3.19", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.19.tgz", + "integrity": "sha512-Y2tUNy4ouw6tq5oDSKeQYGOyhkUBhNOcGV/02KC+6kd9eDGqdZd++mjMiIDilrBYvjEnCYvVtsuHCuP+okSfug==", "dev": true, "funding": [ { @@ -2675,9 +2695,9 @@ } }, "node_modules/node-releases": { - "version": "2.0.46", - "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.46.tgz", - "integrity": "sha512-GYVXHE2KnrzAfsAjl4uP++evGFCrAU1jta4ubEjIG7YWt/64Gqv66a30yKwWczVjA6j3bM4nBwH7Pk1JmDHaxQ==", + "version": "2.0.57", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.57.tgz", + "integrity": "sha512-kQK9LGGFiHtrWiNhZtA7Qbw17AQz+dmsEKODRIVTXA9+e5MS/2gZEBhYJt13GrAz5/IOZKddH/0Z3TP/Zgo+yw==", "dev": true, "license": "MIT", "engines": { @@ -2729,10 +2749,39 @@ "url": "https://github.com/sponsors/jonschlinkert" } }, + "node_modules/playwright": { + "version": "1.63.0", + "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.63.0.tgz", + "integrity": "sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "playwright-core": "1.63.0" + }, + "bin": { + "playwright": "cli.js" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/playwright-core": { + "version": "1.63.0", + "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.63.0.tgz", + "integrity": "sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "playwright-core": "cli.js" + }, + "engines": { + "node": ">=20" + } + }, "node_modules/postcss": { - "version": "8.5.15", - "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz", - "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==", + "version": "8.5.28", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.28.tgz", + "integrity": "sha512-RRuzqDtt5Y9h3quz5hWhK+TPnsmVs6WwSU6LkJMeY4HstUEDuYTG8UJSdawMRzmzAtV+KEoG8N3Qg2qLy5vM/A==", "dev": true, "funding": [ { @@ -2750,7 +2799,7 @@ ], "license": "MIT", "dependencies": { - "nanoid": "^3.3.12", + "nanoid": "^3.3.18", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" }, @@ -3151,9 +3200,9 @@ } }, "node_modules/update-browserslist-db": { - "version": "1.2.3", - "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz", - "integrity": "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==", + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.3.3.tgz", + "integrity": "sha512-pJ2sYawQS0R/WI928Gj5GlPhTGzbMelq0+4INtSYNDV9ErKJcX6xjGWkoG/VnB3dpUm00zALaqkrUD77pO5TDQ==", "dev": true, "funding": [ { @@ -3210,9 +3259,9 @@ } }, "node_modules/vite": { - "version": "6.4.2", - "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.2.tgz", - "integrity": "sha512-2N/55r4JDJ4gdrCvGgINMy+HH3iRpNIz8K6SFwVsA+JbQScLiC+clmAxBgwiSPgcG9U15QmvqCGWzMbqda5zGQ==", + "version": "6.4.3", + "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.3.tgz", + "integrity": "sha512-NTKlcQjlAK7MlQoyb6LgaqHc8sso/pVyUJYWMws3jg21uTJw/LddqIFPcPqP6PzpgbIcZyKI85sFE4HBrQDA8A==", "dev": true, "license": "MIT", "dependencies": { diff --git a/package.json b/package.json index acb52ea..f35d121 100644 --- a/package.json +++ b/package.json @@ -7,10 +7,16 @@ "type": "module", "scripts": { "dev": "vite", - "build": "vite build", + "build": "npm run export && vite build", "preview": "vite preview", "check-links": "node scripts/check-links.mjs", - "validate": "node scripts/check-links.mjs && vite build" + "validate": "npm run check:sync && npm run check-links && npm run typecheck && npm test && npm run build", + "typecheck": "tsc --noEmit", + "test": "node --test test/*.test.mjs", + "test:e2e": "playwright test", + "export": "node scripts/export.mjs", + "sync:openscience": "node scripts/sync-openscience.mjs", + "check:sync": "node scripts/sync-openscience.mjs --check" }, "dependencies": { "lucide-react": "^0.453.0", @@ -24,6 +30,10 @@ "@types/react-dom": "^19.0.0", "@vitejs/plugin-react": "^4.3.4", "typescript": "^5.6.3", - "vite": "^6.0.5" + "vite": "^6.0.5", + "@playwright/test": "1.63.0" + }, + "engines": { + "node": ">=24" } } diff --git a/playwright.config.ts b/playwright.config.ts new file mode 100644 index 0000000..68a42da --- /dev/null +++ b/playwright.config.ts @@ -0,0 +1,15 @@ +import { defineConfig } from "@playwright/test"; + +export default defineConfig({ + testDir: "./e2e", + timeout: 60000, + retries: 0, + workers: 1, + use: { baseURL: "http://127.0.0.1:4180/", viewport: { width: 1440, height: 1000 } }, + webServer: { + command: "npm run build && npm run preview -- --host 127.0.0.1 --port 4180 --strictPort", + url: "http://127.0.0.1:4180/", + reuseExistingServer: !process.env.CI, + timeout: 60000, + }, +}); diff --git a/scripts/check-links.mjs b/scripts/check-links.mjs index c3053a9..90dc50c 100644 --- a/scripts/check-links.mjs +++ b/scripts/check-links.mjs @@ -1,141 +1,59 @@ -// Validates the docs navigation, internal links, and source quality. -// - Every page referenced in a section's docs.json must exist on disk. -// - Every internal MDX link / Card href (/section/page or /page) must resolve. -// - Warns about page files that no nav references (orphans). -// - Rejects long dash punctuation and unlabelled fenced code blocks. -// Exits non-zero on any hard error so it can gate a build. - -import { readFileSync, readdirSync, existsSync, statSync } from "node:fs"; -import { join, dirname, relative } from "node:path"; +import { readFileSync, readdirSync } from "node:fs"; +import { join } from "node:path"; import { fileURLToPath } from "node:url"; +import { aliases, atlasAliases, headings, parseRoute, resolveLink, slug } from "../src/navigation.ts"; -const root = join(dirname(fileURLToPath(import.meta.url)), ".."); -const contentDir = join(root, "src", "content"); - -const SECTIONS = ["openscience", "atlas"]; - -function flattenPages(items) { - return items.flatMap((item) => (typeof item === "string" ? [item] : flattenPages(item.pages))); -} - -function listPageFiles(section) { - const dir = join(contentDir, section); - const out = []; - const walk = (d) => { - for (const entry of readdirSync(d)) { - const full = join(d, entry); - if (statSync(full).isDirectory()) walk(full); - else if (/\.(mdx|md)$/.test(entry)) out.push(relative(dir, full).replace(/\.(mdx|md)$/, "")); - } - }; - walk(dir); - return out; -} - +const root = fileURLToPath(new URL("../src/content/", import.meta.url)); +const sections = ["openscience", "account"]; +const pages = new Map(); const errors = []; -const warnings = []; - -// section -> Set of page paths that exist on disk -const filesBySection = {}; -for (const section of SECTIONS) { - filesBySection[section] = new Set(listPageFiles(section)); -} - -const pageExists = (section, path) => - SECTIONS.includes(section) && filesBySection[section].has(path || "index"); - -// 1. Nav config references resolve, and collect referenced pages. -const navReferenced = {}; -for (const section of SECTIONS) { - navReferenced[section] = new Set(); - const configPath = join(contentDir, section, "docs.json"); - if (!existsSync(configPath)) { - errors.push(`Missing docs.json for section "${section}"`); - continue; - } - const config = JSON.parse(readFileSync(configPath, "utf8")); - const pages = config.navigation.tabs.flatMap((tab) => - tab.groups.flatMap((group) => flattenPages(group.pages)), - ); - for (const page of pages) { - navReferenced[section].add(page); - if (!filesBySection[section].has(page)) { - errors.push(`[nav] ${section}/docs.json references "${page}" but src/content/${section}/${page}.mdx is missing`); - } - } -} - -// 2. Orphans: page files not referenced by their section nav. -for (const section of SECTIONS) { - for (const file of filesBySection[section]) { - if (!navReferenced[section].has(file)) { - warnings.push(`[orphan] src/content/${section}/${file}.mdx is not referenced in ${section}/docs.json`); - } - } -} - -// 3. Internal links in MDX (markdown links + Card/href). -const linkRe = /\]\((\/[^)\s]+)\)/g; -const hrefRe = /href=["'](\/[^"']+)["']/g; - -for (const section of SECTIONS) { - for (const file of filesBySection[section]) { - const filePath = existsSync(join(contentDir, section, `${file}.mdx`)) - ? join(contentDir, section, `${file}.mdx`) - : join(contentDir, section, `${file}.md`); - const src = readFileSync(filePath, "utf8"); - - if (/[\u2014\u2013]/.test(src)) { - errors.push(`[style] ${section}/${file}.mdx contains an em dash or en dash`); - } - - let inFence = false; - src.split("\n").forEach((line, index) => { +const flatten = (items) => items.flatMap((item) => typeof item === "string" ? [item] : flatten(item.pages)); + +for (const section of sections) { + const directory = join(root, section); + const config = JSON.parse(readFileSync(join(directory, "docs.json"), "utf8")); + const order = config.navigation.tabs.flatMap((tab) => tab.groups.flatMap((group) => flatten(group.pages))); + if (new Set(order).size !== order.length) errors.push(`${section}: duplicate navigation entry`); + for (const file of readdirSync(directory).filter((name) => name.endsWith(".mdx"))) { + const path = file.slice(0, -4); + const source = readFileSync(join(directory, file), "utf8"); + if (!/^---\ntitle: ".+"\ndescription: ".+"\n(?:[\s\S]*?\n)?---/m.test(source)) errors.push(`${section}/${path}: missing quoted title or description`); + const body = source.replace(/^---\n[\s\S]*?\n---\n?/, ""); + const anchors = headings(body, 3).map(slug); + if (new Set(anchors).size !== anchors.length) errors.push(`${section}/${path}: duplicate heading anchors`); + if (!order.includes(path)) errors.push(`${section}/${path}: missing from navigation`); + const state = { fence: false }; + for (const line of body.split("\n")) { const fence = line.match(/^\s*```(.*)$/); - if (!fence) return; - if (!inFence && !fence[1].trim()) { - errors.push(`[code] ${section}/${file}.mdx:${index + 1} has a fenced code block without a language`); - } - inFence = !inFence; - }); - if (inFence) { - errors.push(`[code] ${section}/${file}.mdx has an unclosed fenced code block`); - } - - const hrefs = new Set(); - let m; - while ((m = linkRe.exec(src))) hrefs.add(m[1]); - while ((m = hrefRe.exec(src))) hrefs.add(m[1]); - - for (const href of hrefs) { - const clean = href.split("#")[0].replace(/\/$/, ""); - if (!clean || clean === "/") continue; - const segments = clean.slice(1).split("/"); - let targetSection; - let targetPath; - if (SECTIONS.includes(segments[0])) { - targetSection = segments[0]; - targetPath = segments.slice(1).join("/") || "index"; - } else { - targetSection = section; - targetPath = segments.join("/"); - } - if (!pageExists(targetSection, targetPath)) { - errors.push(`[link] ${section}/${file}.mdx -> "${href}" does not resolve (${targetSection}/${targetPath})`); - } + if (!fence) continue; + if (!state.fence && !fence[1].trim()) errors.push(`${section}/${path}: code block needs a language`); + state.fence = !state.fence; } + if (state.fence) errors.push(`${section}/${path}: unclosed code block`); + pages.set(`${section}/${path}`, { body, anchors, section, path }); + } + for (const path of order) if (!pages.has(`${section}/${path}`)) errors.push(`${section}: missing page ${path}`); +} + +let links = 0; +for (const [name, page] of pages) { + const prose = page.body.replace(/```[\s\S]*?```/g, ""); + const hrefs = [...prose.matchAll(/\[[^\]]*\]\(([^)\s]+)\)|href=["']([^"']+)["']/g)].map((match) => match[1] ?? match[2]); + for (const href of hrefs) { + links++; + if (/^(https?:|mailto:|tel:)/.test(href)) { new URL(href); continue; } + const route = parseRoute(resolveLink(href, page)); + const target = pages.get(`${route.section}/${route.path}`); + if (!target) errors.push(`${name}: broken link ${href}`); + else if (route.anchor && !target.anchors.includes(route.anchor)) errors.push(`${name}: missing anchor ${href}`); } } - -const total = SECTIONS.reduce((n, s) => n + filesBySection[s].size, 0); -console.log(`Checked ${total} pages across ${SECTIONS.length} sections.`); -if (warnings.length) { - console.log(`\n${warnings.length} warning(s):`); - for (const w of warnings) console.log(" " + w); +for (const [old, path] of Object.entries(aliases)) { + if (!pages.has(`openscience/${path}`)) errors.push(`Missing OpenScience redirect target: ${old} -> ${path}`); + if (pages.has(`openscience/${old}`)) errors.push(`OpenScience redirect shadows page: ${old}`); } -if (errors.length) { - console.error(`\n${errors.length} error(s):`); - for (const e of errors) console.error(" " + e); - process.exit(1); +for (const [old, route] of Object.entries(atlasAliases)) { + if (!pages.has(`${route.section}/${route.path}`)) errors.push(`Missing Atlas redirect target: ${old}`); } -console.log("\nAll nav entries, internal links, and content checks pass. No 404s."); +if (errors.length) throw new Error(errors.join("\n")); +console.log(`Validated ${pages.size} pages, ${links} links, heading anchors, navigation, and legacy redirects.`); diff --git a/scripts/export.mjs b/scripts/export.mjs new file mode 100644 index 0000000..9201cdb --- /dev/null +++ b/scripts/export.mjs @@ -0,0 +1,38 @@ +import { readFile, writeFile } from "node:fs/promises"; +import { fileURLToPath } from "node:url"; +import { join } from "node:path"; +import { parseRoute, resolveLink } from "../src/navigation.ts"; + +const root = fileURLToPath(new URL("../", import.meta.url)); +const base = "https://docs.syntheticsciences.ai/"; +const index = ["# Synthetic Sciences documentation", "", "> OpenScience research guides, Ace, account workspaces, and private Graphs.", "", `Full text: ${base}llms-full.txt`, ""]; +const full = ["# Synthetic Sciences documentation", "", `Source: ${base}`, ""]; +for (const section of ["openscience", "account"]) { + const directory = join(root, "src/content", section); + const config = JSON.parse(await readFile(join(directory, "docs.json"), "utf8")); + index.push(`## ${config.name}`, ""); + for (const tab of config.navigation.tabs) { + for (const group of tab.groups) { + index.push(`### ${group.group}`, ""); + for (const path of group.pages) { + const raw = await readFile(join(directory, path + ".mdx"), "utf8"); + const title = raw.match(/^title: "(.+)"$/m)[1]; + const description = raw.match(/^description: "(.+)"$/m)[1]; + const url = `${base}#/${section}/${path}`; + const body = raw.replace(/^---\n[\s\S]*?\n---\n?/, "") + .replace(/\s*([\s\S]*?)\s*<\/Card>/g, "[$1]($2): $3") + .replace(/<\/?(?:Columns|CardGroup)\b[^>]*>/g, "") + .replace(/\]\(([\/#][^)]*)\)/g, (_, href) => { + const route = parseRoute(resolveLink(href, { section, path })); + return `](${base}#/${route.section}/${route.path}${route.anchor ? "#" + route.anchor : ""})`; + }); + index.push(`- [${title}](${url}): ${description}`); + full.push(`# ${title}`, "", description, "", `URL: ${url}`, "", body.trim(), ""); + } + index.push(""); + } + } +} +await writeFile(join(root, "public/llms.txt"), index.join("\n")); +await writeFile(join(root, "public/llms-full.txt"), full.join("\n")); +console.log("Generated documentation index and full-text exports."); diff --git a/scripts/openscience-source.json b/scripts/openscience-source.json new file mode 100644 index 0000000..9cd7fa0 --- /dev/null +++ b/scripts/openscience-source.json @@ -0,0 +1,78 @@ +{ + "repository": "https://github.com/synthetic-sciences/openscience", + "revision": "34f36e65b6aa76e6ce4e785dd7914699b236ea4b", + "directory": "frontend/docs/src/content/openscience", + "files": { + "account.mdx": "78ce6e8907ddbe95f7ba9954e2370ba9fd3fddc95787a701b920a1c96c7e46f3", + "ace-models.mdx": "ddee96cbb897d4ed5418711aec588f1e8e666bfd26476ae367e19fe63d2732ae", + "ace.mdx": "f7330afef2f4c96c248ed209290ba8bd6cf140ab0b9b3c45b7140836e5b98036", + "agents.mdx": "296796b4a965dc09895fc3ab46029f482781ff1ca63dc6398ec06fc83b1fd3cd", + "api.mdx": "62fad09437f660dd057a2da1fa50622193d4fc63853870f5a54950b8dc9f6142", + "automation.mdx": "73f9672b8dad4a0bcb9c190f1fb6a15fb1c56dcfc5f78491bcc8d1ef42af3eca", + "autoresearch.mdx": "866437a93c397a1c952d341138a2b33a9f28b509db5ec2ff0e60e6359298c30e", + "built-in-tools.mdx": "203e3e948cf09743a8562d477c8f5cee205661d67dbdc16fa34917d7b64d5b38", + "capabilities.mdx": "5042033d17820a8b1fac1f95459d25512c51440b736becc3d796fe9f20ab9bee", + "code.mdx": "f9e9c3b80827d7323fc705d3a67297a5d14d3ce4fed8403f394b4e956a73b341", + "commands.mdx": "a8ebc3f0339a703fb680d9c7d377a4d5d99a518e1b5d6b3a84290662061b725b", + "compute.mdx": "a4ff8bf382e893949a1a555e7a282e6c3b6c0ebdf09ca65f5abcead3a6f8d481", + "configuration.mdx": "bc0d61d14334aad23fcf294fef9d81be559c5e49fd35bf0728434465e8d442f9", + "connectors.mdx": "f7bb6e1b303a87e715a318bfa14f7ee1c788e3cd5125eb52c4a05234138cbc28", + "context.mdx": "0845be835c1cc9ceaea5ee2d26fe90524549678acb1e17840433831644693618", + "custom-providers.mdx": "25cf740bd373d8cd77ad3e463c6975317feca0d9d8e7fe52f9357a688f207575", + "custom-tools.mdx": "20954b6b41e5a5dcb09ecd46dc4e8fb98c4549f0104ff642394f4f1b761dd559", + "data-analysis.mdx": "b997755cbfaac9ba58f9ad83f05c2bab3b28619978e29aa20017439c02a6ada7", + "database-workflows.mdx": "cd80e8678f6470c89f837633c0cc09b8db37f8893cf5f8be7e2aaf02681376a8", + "databases.mdx": "68520798d19714d6cafc159c717b0f51f6980c1795b268e4a985bc4b00f2966d", + "docs.json": "9530ae9a79b55426bd2355e41af9b752918c60fc7bd24430323efadd4d22c46d", + "documents.mdx": "9b1d1bdc127ba8de81d5e664007c4ea048201ecd7cfa2abf4c8745ca3801fa19", + "experiment-tracking.mdx": "3f88fd1a5a219528d0dd3db9de3addf884e157acda365b9727a553dfa5f87ddb", + "explore-tools.mdx": "850b668fff34f02cbf44f72bee79e5ce1280dc97f9d97929cdf922c1fee78c3e", + "extensions.mdx": "0f918df8dcfc699a917d3a22e9443ac30bd1c351bf06dc9db4623b41748082ba", + "faq.mdx": "c56c0c0eea8ae5ebe53f7d0ce5e781f14796fa72f9dc8cb944bfe400e5eb784a", + "figures.mdx": "e4b6dcaea72a35c5c10db9725398cafedfb521314fec00b59ee12a3d2e89f8fa", + "files.mdx": "a993d000291704012fdf7cb5f0da7b302fb292b47af46702e67249cddabdbdd6", + "genomics.mdx": "0faf788b17b0214a07b21c7040a826f2d7d04863dfabe65debdc693707820378", + "image-generation.mdx": "3f10a46881b179190a00ed690db0203568795a8e5cb4d2e26a6d74ebe1049987", + "index.mdx": "9a9569a442a83a0048a96bcda1799e9b6660b8a2ebfbe8f0529bb9bcabe012de", + "installation.mdx": "b84a0900a5a9d62b58deded563bd942b21cb11d9eba8dc7b0dccb093b0a3039d", + "instructions.mdx": "db66978a4461d000f18cd518d8f7991a1884f141d4b4f398c0f7beaa8fc9d45c", + "jobs.mdx": "c2d1f9ef0ce35b28f0623097bb6dec8c507abf3dafcf9e9df2bd83528dc29837", + "keyboard-shortcuts.mdx": "98428ecc7dd90d8ac4600284748572cca2649bef5e9db43af603ebcb82c98fc1", + "literature-review.mdx": "23b3ff8b60352a0b1c30cdbff7543491dc8d229560413af6391d4ae821d955d9", + "local-models.mdx": "91c480a7c6c30a02227eb0e3e38d69d753f6a1f64ca78b1b39db8e12582d94af", + "machine-learning.mdx": "c7d2c49be54daa88da0b36197895bea191cf2c840f83ca0d49aa2b4a5d4098e2", + "models.mdx": "fadea7c6fc8fcad2a317e789e6a6497d018453027c43580b9d235bdc973114c0", + "molecular-research.mdx": "18666855aaea9d8ddcbc0e91530a1c92f802a7d1427bd7dc42346dd80bd84892", + "permissions.mdx": "a18149bca2756716664809d22be7161a5e750e9ae398ed794ea70b76c55be92d", + "planning.mdx": "c06ce950b832657c99c3907dc0f335b05ea2d351ab97e3b443f0cf01a4f5275e", + "preferences.mdx": "0f76d30f41c6685dd3cfc91aeb6a5c46859e0101c41ff9bd63da352c3cef235a", + "pricing.mdx": "6b17856f82ad3b1c42215544cffa7f727d54fbd9f1cfd15442ef5baecc4de5bd", + "privacy.mdx": "1c5954a8984202cc461d41879732cbf0559c7be5dd71e03d9e0affa77da0d774", + "projects.mdx": "843987c26d23239382f455ef3555eeb7c6844057ae463f1d76d787385c23a336", + "python-r.mdx": "03a5d4306e7c8db47a497e6ac7ea8d806f8dbb45ee5c0a6abab2dee6be3518fc", + "quickstart.mdx": "3587ad9f2757f049db0d5c6723656c01882c3343fa9d41379d72c460075301d4", + "remote-compute.mdx": "af17b0c0567b9e36538a062d8a986b4517b1f922a3ad14b1018797f5756e0a72", + "reproduction.mdx": "ced31d8a2ad91e923c1a1e5884246197168a3e312fb1baad474b171e838e1f57", + "research-search.mdx": "239c26ea1818652c8e367866681361fff3236f6cd8e5a72a109eb6adbe7eeda2", + "results.mdx": "13e5fb35e80dfc14d31bec1d987a6820bbe720115fab66e700766e49f427abed", + "scientific-tools.mdx": "36448c9a0e7c3d63efa00fdffdd75c8e73fd0f18e1dac29b25ddd0af536b0e31", + "scientific-viewers.mdx": "fc9c0b60fa1b0cb0f25a93a1e517d8413bd48f047dde4be98ac8c43a98c6ac79", + "server-hosting.mdx": "eef5d351165b46e4322f5f2b54dd59a2f0b4dcc220a19ab9780d40f10b242b41", + "service-credentials.mdx": "eb85dc026c93deed9a1ab66f0ddbd897399d7361ea53e3b33b7694db793f79dd", + "sessions.mdx": "5dcbb7bdc30e73906e02073a9ee323e05f4502b13a84345dc22a4212371f92cf", + "skill-library.mdx": "1c9fee186bb8ea143f40c4ecbb6f8d0917aab880b763e8f6b9f9c0d2f21bc467", + "skill-workflows.mdx": "7aa47804817f82a5b04d81ebea78ad799bf5975f8f59ef0bc8efb78ffb9b8d17", + "skills.mdx": "54041026e53b2c004df8ecc885a27ffa6bcae3ab71b841d3b7d0e352b4b483f0", + "slash-commands.mdx": "f6282380ec998eb779d8612849748251394cc62e6dec20b2837210c689b52fba", + "source-types.mdx": "d4a206f85ac10817da2008341700cbd16feb5ba1216d5ddb961e7148ad405856", + "statistics.mdx": "99d886d30e6431dbb1377d7f07dbd0b4ef1d9140e5aa9869d39c0b796473d53d", + "tables.mdx": "0867b1b1be5b9a46b0731034d3ebfcce699da3fd71453f264cb8286eac10ec05", + "team-workflows.mdx": "76489c17fa07697daf548b8b6aa717ee7a1b4ba1add80e6a13cc24f180ec9272", + "tool-catalog.mdx": "2c1c359f2c7bb46fb8050f6ed9c2acef75c35aebcc15543b68c14eb1847fb12b", + "troubleshooting.mdx": "c359b12f7670a09298201837f58920e00f06e5ede702acc70b8cd69b043f28bd", + "usage.mdx": "94a5f53e1deb302e57a133e5f2597e188c1cb45acd2528efece21ec38ea0b1b4", + "workflow-examples.mdx": "e7d1b8b80fbcc74e4dbd6f0b7e4e9af601e003c633f0c467a957c44ce47d49e9", + "workspace.mdx": "01cc9e5445ee3f8cb7e6a6e997b3f6e983afc1dc6aab805b8fc7cdbf895c2c6d", + "writing.mdx": "3e3d92c4bc2920f7e644cbcb549e20a64f19822e9c3c5a6d82f7770ec201b88f" + } +} diff --git a/scripts/sync-openscience.mjs b/scripts/sync-openscience.mjs new file mode 100644 index 0000000..4dd38db --- /dev/null +++ b/scripts/sync-openscience.mjs @@ -0,0 +1,42 @@ +import { createHash } from "node:crypto"; +import { execFileSync } from "node:child_process"; +import { readFile, writeFile, readdir, mkdir, rm } from "node:fs/promises"; +import { resolve, join } from "node:path"; +import { fileURLToPath } from "node:url"; + +const root = fileURLToPath(new URL("../", import.meta.url)); +const target = join(root, "src/content/openscience"); +const manifestPath = join(root, "scripts/openscience-source.json"); +const args = process.argv.slice(2); +const check = args.includes("--check"); +const sourceArg = args.indexOf("--source"); +const source = sourceArg >= 0 ? args[sourceArg + 1] : undefined; +if ((!check && !source) || (sourceArg >= 0 && (!source || source.startsWith("--")))) { + throw new Error("Usage: npm run sync:openscience -- --source /path/to/openscience [--check], or --check alone"); +} +const directory = source ? join(resolve(source), "frontend/docs/src/content/openscience") : target; +const names = (await readdir(directory)).filter((name) => name.endsWith(".mdx") || name === "docs.json").sort(); +const files = Object.fromEntries(await Promise.all(names.map(async (name) => [name, await readFile(join(directory, name))]))); +const hashes = Object.fromEntries(names.map((name) => [name, createHash("sha256").update(files[name]).digest("hex")])); + +if (check) { + const manifest = JSON.parse(await readFile(manifestPath, "utf8")); + const local = (await readdir(target)).filter((name) => name.endsWith(".mdx") || name === "docs.json").sort(); + if (JSON.stringify(names) !== JSON.stringify(local)) throw new Error("OpenScience page inventory differs; run sync:openscience."); + for (const name of names) { + if (source && !(await readFile(join(target, name))).equals(files[name])) throw new Error(`OpenScience mirror differs: ${name}`); + } + if (JSON.stringify(hashes) !== JSON.stringify(manifest.files)) throw new Error("OpenScience content differs from its recorded source; update the canonical repository and sync again."); + console.log(`Verified ${names.length - 1} OpenScience pages and navigation against ${manifest.revision}.`); +} else { + const revision = execFileSync("git", ["-C", resolve(source), "rev-parse", "HEAD"], { encoding: "utf8" }).trim(); + const dirty = execFileSync("git", ["-C", resolve(source), "status", "--porcelain", "--", "frontend/docs/src/content/openscience"], { encoding: "utf8" }).trim(); + if (dirty) throw new Error("Commit canonical OpenScience content before syncing so provenance names an exact revision."); + await mkdir(target, { recursive: true }); + for (const name of await readdir(target)) { + if ((name.endsWith(".mdx") || name === "docs.json") && !names.includes(name)) await rm(join(target, name)); + } + for (const name of names) await writeFile(join(target, name), files[name]); + await writeFile(manifestPath, JSON.stringify({ repository: "https://github.com/synthetic-sciences/openscience", revision, directory: "frontend/docs/src/content/openscience", files: hashes }, null, 2) + "\n"); + console.log(`Synced ${names.length - 1} OpenScience pages and navigation from ${revision}.`); +} diff --git a/src/DocsApp.tsx b/src/DocsApp.tsx index 9921f13..826e05a 100644 --- a/src/DocsApp.tsx +++ b/src/DocsApp.tsx @@ -35,6 +35,7 @@ import { Workflow, } from "lucide-react"; import { useTheme } from "./theme"; +import { headings, pageHref, parseRoute, resolveLink, slug, type Route, type SectionKey } from "./navigation"; const mono = `"JetBrains Mono", "SF Mono", ui-monospace, monospace`; @@ -91,8 +92,6 @@ type MintlifyCard = { horizontal?: boolean; }; -type SectionKey = "openscience" | "atlas"; - type Section = { key: SectionKey; label: string; @@ -101,10 +100,10 @@ type Section = { lead: boolean; }; -// The two Synthetic Sciences products, in order. +// Product guides and the shared account service. const SECTIONS: Section[] = [ { key: "openscience", label: "OpenScience", short: "OpenScience", tagline: "Open-source AI workbench", lead: false }, - { key: "atlas", label: "Atlas", short: "Atlas", tagline: "The research graph", lead: false }, + { key: "account", label: "Synthetic Sciences", short: "Account & Graphs", tagline: "Ace, workspaces, and private research", lead: false }, ]; const SECTION_KEYS = SECTIONS.map((section) => section.key); @@ -165,7 +164,7 @@ const ICONS: Record = { const SECTION_FALLBACK_ICON: Record = { openscience: , - atlas: , + account: , }; const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/; @@ -190,14 +189,6 @@ function parseFrontmatter(source: string): { title: string; description: string; }; } -function extractHeadings(markdown: string): string[] { - return markdown - .split("\n") - .filter((line) => line.startsWith("## ")) - .map((line) => line.replace(/^##\s+/, "").trim()) - .slice(0, 10); -} - function flattenPages(items: Array): string[] { return items.flatMap((item) => (typeof item === "string" ? [item] : item.pages)); } @@ -220,7 +211,7 @@ function buildSectionPages(section: SectionKey): Record { description: parsed.description, icon: iconForPath(path, section), body: parsed.body, - headings: extractHeadings(parsed.body), + headings: headings(parsed.body), }; } return pages; @@ -228,81 +219,12 @@ function buildSectionPages(section: SectionKey): Record { const SECTION_DOC_PAGES: Record> = { openscience: buildSectionPages("openscience"), - atlas: buildSectionPages("atlas"), + account: buildSectionPages("account"), }; const SECTION_CONFIGS: Record = { openscience: RAW_CONFIGS["./content/openscience/docs.json"], - atlas: RAW_CONFIGS["./content/atlas/docs.json"], -}; - -function pageExists(section: SectionKey, path: string): boolean { - return Boolean(SECTION_DOC_PAGES[section]?.[path]); -} - -// Redirects from retired section names (and the per-page renames inside them) -// to the current two sections. Applied to the first URL segment. -const SECTION_ALIASES: Record = { - "getting-started": "atlas", - graphs: "atlas", - "agent-cli": "openscience", -}; - -// Old agent-cli page names that moved during the OpenScience rebuild. -const PAGE_ALIASES: Record = { - "first-session": "sessions", - "sub-agents": "agents", - "web-ui": "workspace", - "server-mode": "workspace", - "cli-runtime": "commands", - "feature-map": "commands", - codex: "models", - credentials: "ace", - connect: "ace", - gateway: "ace", - atlas: "ace", - security: "permissions", - sandbox: "permissions", - artifacts: "results", - "scientific-data": "databases", -}; - -// Redirects from the oldest two-toggle URLs (#/path with product in -// localStorage) to the #/
/ scheme. Keyed by `${oldProduct}:${oldPath}`. -const LEGACY_REDIRECTS: Record = { - "atlas:index": { section: "atlas", path: "index" }, - "atlas:quickstart": { section: "atlas", path: "installation" }, - "atlas:agent-onboarding": { section: "atlas", path: "onboard-agent" }, - "atlas:auth-config": { section: "atlas", path: "authentication" }, - "atlas:cli-runtime": { section: "atlas", path: "cli-overview" }, - "atlas:feature-map": { section: "atlas", path: "cli-overview" }, - "atlas:api-reference/introduction": { section: "atlas", path: "rest-api" }, - "atlas:api-reference/atlas-rest": { section: "atlas", path: "rest-api" }, - "atlas:first-graph": { section: "atlas", path: "quickstart" }, - "atlas:graph": { section: "atlas", path: "graph-model" }, - "atlas:artifacts-files": { section: "atlas", path: "evidence" }, - "atlas:exports-imports": { section: "atlas", path: "forking" }, - "atlas:commands": { section: "atlas", path: "commands" }, - "atlas:skills": { section: "atlas", path: "skills" }, - "atlas:safety": { section: "atlas", path: "cli-overview" }, - "cli:index": { section: "openscience", path: "index" }, - "cli:installation": { section: "openscience", path: "quickstart" }, - "cli:quickstart": { section: "openscience", path: "quickstart" }, - "cli:first-session": { section: "openscience", path: "sessions" }, - "cli:agent-onboarding": { section: "atlas", path: "onboard-agent" }, - "cli:sessions": { section: "openscience", path: "sessions" }, - "cli:models": { section: "openscience", path: "models" }, - "cli:codex": { section: "openscience", path: "models" }, - "cli:sub-agents": { section: "openscience", path: "agents" }, - "cli:skills": { section: "openscience", path: "skills" }, - "cli:cli-runtime": { section: "openscience", path: "commands" }, - "cli:connect": { section: "openscience", path: "ace" }, - "cli:credentials": { section: "openscience", path: "ace" }, - "cli:security": { section: "openscience", path: "permissions" }, - "cli:feature-map": { section: "openscience", path: "commands" }, - "cli:commands": { section: "openscience", path: "commands" }, - "cli:web-ui": { section: "openscience", path: "workspace" }, - "cli:server-mode": { section: "openscience", path: "workspace" }, + account: RAW_CONFIGS["./content/account/docs.json"], }; function readStoredProduct(): "atlas" | "cli" { @@ -316,68 +238,22 @@ function readStoredProduct(): "atlas" | "cli" { return "cli"; } -type Route = { section: SectionKey; path: string }; - -function defaultRoute(): Route { - return { section: "openscience", path: "index" }; -} - function routeFromHash(): Route { - if (typeof window === "undefined") return defaultRoute(); - const raw = decodeURIComponent(window.location.hash.replace(/^#\/?/, "")).replace(/\/$/, ""); - if (!raw) return defaultRoute(); - const segments = raw.split("/"); - const maybeSection = segments[0] as SectionKey; - if (SECTION_KEYS.includes(maybeSection)) { - const path = segments.slice(1).join("/") || "index"; - if (pageExists(maybeSection, path)) return { section: maybeSection, path }; - return { section: maybeSection, path: "index" }; - } - // Retired section names redirect into the current two-section scheme. - const aliasSection = SECTION_ALIASES[segments[0]]; - if (aliasSection) { - const rawPath = segments.slice(1).join("/") || "index"; - const path = PAGE_ALIASES[rawPath] ?? rawPath; - if (pageExists(aliasSection, path)) return { section: aliasSection, path }; - return { section: aliasSection, path: "index" }; - } - // Legacy single-segment URL: disambiguate via the stored product toggle. - const product = readStoredProduct(); - const redirect = LEGACY_REDIRECTS[`${product}:${raw}`] ?? LEGACY_REDIRECTS[`cli:${raw}`] ?? LEGACY_REDIRECTS[`atlas:${raw}`]; - if (redirect && pageExists(redirect.section, redirect.path)) return redirect; - return defaultRoute(); -} - -function pageHref(section: SectionKey, path: string): string { - return `#/${section}/${path}`; + return parseRoute(typeof window === "undefined" ? "" : window.location.hash, readStoredProduct()); } -// Module-level pointers updated on each render so the markdown renderer (which -// can't take props through react-markdown) can resolve links and card icons. -let CURRENT_SECTION: SectionKey = "openscience"; +// Shared by Markdown links and cards during the current render. +let CURRENT_ROUTE: Route = { section: "openscience", path: "index" }; function resolveHref(href: string | undefined): string | undefined { - if (!href) return href; - if (href.startsWith("http") || href.startsWith("#") || href.startsWith("mailto:")) return href; - if (href.startsWith("/")) { - const clean = href.slice(1).replace(/\/$/, ""); - if (!clean) return pageHref(CURRENT_SECTION, "index"); - const segments = clean.split("/"); - const maybeSection = segments[0] as SectionKey; - if (SECTION_KEYS.includes(maybeSection)) { - const path = segments.slice(1).join("/") || "index"; - if (pageExists(maybeSection, path)) return pageHref(maybeSection, path); - } - if (pageExists(CURRENT_SECTION, clean)) return pageHref(CURRENT_SECTION, clean); - } - return href; + return resolveLink(href, CURRENT_ROUTE); } function sectionForHref(href: string): SectionKey { const clean = href.replace(/^#\/?/, "").replace(/\/$/, ""); const segments = clean.split("/"); const maybeSection = segments[0] as SectionKey; - return SECTION_KEYS.includes(maybeSection) ? maybeSection : CURRENT_SECTION; + return SECTION_KEYS.includes(maybeSection) ? maybeSection : CURRENT_ROUTE.section; } function parseMdxAttrs(attrs: string): Record { @@ -490,30 +366,35 @@ function GitHubStars() { } function CopyButton({ text }: { text: string }) { - const [copied, setCopied] = useState(false); + const [status, setStatus] = useState("copy"); return ( ); } const markdownComponents: Components = { h2({ children }) { - const id = String(children).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""); + const id = slug(extractCodeText(children)); return

{children}

; }, + h3({ children }) { + return

{children}

; + }, a({ href, children }) { const external = href?.startsWith("http"); const internalDocsHref = href ? resolveHref(href) : undefined; @@ -683,13 +564,19 @@ export function DocumentationPage() { const { theme, toggle: toggleTheme } = useTheme(); const [route, setRouteState] = useState(() => routeFromHash()); const section = route.section; - CURRENT_SECTION = section; + CURRENT_ROUTE = route; const docPages = SECTION_DOC_PAGES[section]; const config = SECTION_CONFIGS[section]; const sectionMeta = SECTIONS.find((entry) => entry.key === section) ?? SECTIONS[0]; - const activePage = docPages[route.path] ?? docPages.index; + const activePage = docPages[route.path] ?? { + path: route.path, title: "Page not found", description: "This documentation page does not exist.", + body: "Return to [OpenScience](/openscience/index) or [Synthetic Sciences](/account/index), or search the documentation.", + icon: SECTION_FALLBACK_ICON[section], headings: [], + }; const [query, setQuery] = useState(""); const [searchOpen, setSearchOpen] = useState(false); + const [searchIndex, setSearchIndex] = useState(0); + const [menuOpen, setMenuOpen] = useState(false); const navTabs = config.navigation.tabs; const orderedPaths = useMemo( @@ -744,11 +631,15 @@ export function DocumentationPage() { const haystack = `${page.title} ${page.description} ${page.sectionLabel} ${body}`.toLowerCase(); return haystack.includes(normalizedQuery); }) + .sort((a, b) => { + const score = (page: SearchResult) => page.title.toLowerCase() === normalizedQuery ? 3 : page.title.toLowerCase().includes(normalizedQuery) ? 2 : page.description.toLowerCase().includes(normalizedQuery) ? 1 : 0; + return score(b) - score(a); + }) .slice(0, 8); }, [query, section]); const navigate = (next: Route) => { - window.location.hash = pageHref(next.section, next.path); + window.location.hash = pageHref(next.section, next.path, next.anchor); setRouteState(next); }; @@ -760,18 +651,24 @@ export function DocumentationPage() { // Keep the URL canonical (legacy + bare hashes resolve to #/
/). useEffect(() => { - const canonical = pageHref(route.section, route.path); + const canonical = pageHref(route.section, route.path, route.anchor); if (window.location.hash !== canonical) { window.history.replaceState(null, "", canonical); } - }, [route.section, route.path]); + }, [route]); - // Hash-based page changes do not trigger the browser's normal document - // navigation scroll reset. Without this, opening another guide can leave the - // reader halfway down the new page. useEffect(() => { - window.scrollTo({ top: 0, left: 0, behavior: "auto" }); - }, [route.section, route.path]); + if (route.anchor) document.getElementById(route.anchor)?.scrollIntoView({ block: "start" }); + else window.scrollTo({ top: 0, left: 0, behavior: "auto" }); + setMenuOpen(false); + setSearchOpen(false); + }, [route.section, route.path, route.anchor]); + + useEffect(() => { + document.title = activePage.title + " · Synthetic Sciences Docs"; + const description = document.querySelector('meta[name="description"]'); + description?.setAttribute("content", activePage.description); + }, [activePage.title, activePage.description]); useEffect(() => { const onKeyDown = (event: KeyboardEvent) => { @@ -805,26 +702,47 @@ export function DocumentationPage() { { + if (event.key === "Escape") { event.preventDefault(); event.stopPropagation(); setSearchOpen(false); return; } + if (event.key === "ArrowDown" || event.key === "ArrowUp") { + event.preventDefault(); + setSearchOpen(true); + setSearchIndex((index) => Math.max(0, Math.min(searchResults.length - 1, index + (event.key === "ArrowDown" ? 1 : -1)))); + } + if (event.key === "Enter" && searchOpen && searchResults[searchIndex]) { + event.preventDefault(); + navigate(searchResults[searchIndex]); + setQuery(""); + setSearchOpen(false); + } + }} value={query} onBlur={() => window.setTimeout(() => setSearchOpen(false), 120)} onChange={(event) => { setQuery(event.target.value); + setSearchIndex(0); setSearchOpen(true); }} - onFocus={() => setSearchOpen(true)} + onFocus={() => { setSearchOpen(true); setSearchIndex(0); }} placeholder="Search all docs..." type="search" /> ⌘K {searchOpen ? ( -
+ +
-
+
); @@ -1927,6 +1847,10 @@ const docsCss = ` font-size: 11px; } + .docs-menu-toggle { display: none; } + .docs-footer { display: flex; flex-wrap: wrap; justify-content: center; gap: 24px; padding: 24px; font-size: 12px; } + .docs-markdown h2, .docs-markdown h3 { scroll-margin-top: 150px; } + .docs-search-results a[aria-selected="true"] { background: var(--color-bg-subtle); } @media (max-width: 1180px) { .docs-shell { grid-template-columns: 224px minmax(0, 1fr); @@ -1940,19 +1864,24 @@ const docsCss = ` @media (max-width: 860px) { .docs-topbar { grid-template-columns: minmax(0, 1fr) auto; - padding: 0 16px; + padding: 12px 16px; + height: auto; + gap: 12px; + position: static; } .docs-search { grid-column: 1 / -1; order: 2; - display: none; + display: flex; } .docs-topbar nav a:not(.docs-topbar-cta) { display: none; } + .docs-sectionbar { top: 0; } + .docs-sectionbar-inner { padding: 0 16px; } @@ -1966,6 +1895,8 @@ const docsCss = ` padding: 22px 16px 64px; } + .docs-menu-toggle { display: block; margin: 16px 16px 0; padding: 10px 14px; border: 1px solid var(--color-border); border-radius: 6px; background: var(--color-bg-subtle); color: var(--color-text); } + .docs-sidebar:not(.docs-sidebar-open) { display: none; } .docs-sidebar { position: static; border: 1px solid var(--color-border); diff --git a/src/content/account/api-keys.mdx b/src/content/account/api-keys.mdx new file mode 100644 index 0000000..98d8cc1 --- /dev/null +++ b/src/content/account/api-keys.mdx @@ -0,0 +1,36 @@ +--- +title: "Workspace API keys" +description: "Create, use, and revoke keys that connect OpenScience to a specific workspace." +--- + +## Create a key + +1. Choose the intended workspace in the [dashboard](https://app.syntheticsciences.ai/workspaces). +2. Open **API Keys** and select **New key**. +3. Enter a name such as `Research laptop` or `CI runner`, then select **Create key**. +4. Copy the secret from **Save your key** before selecting **Done**. It cannot be shown again after that panel closes. + +Current workspace keys begin with `osk_`. Existing keys may be marked **Legacy key**. A key's prefix identifies its format, not permission to use every account API. + +## Connect OpenScience + +Open **Customize → Models → Ace → Use an API key** and paste the key. For automated setup, the CLI supports `openscience login --key `; replace the placeholder using the runner's secret store. Prefer the app's input for interactive setup so a secret is not saved in shell history. + +```bash +openscience status +openscience wallet show +``` + +Confirm the workspace before starting paid work. The key is pinned to its issuing workspace. A browser selection, project folder, or another signed-in account does not override its funding scope. + +## Inspect and revoke access + +The key list shows the name, creator, prefix, creation and last-used dates, and active or revoked status. Use a separate named key for each device or automation so you can revoke the right one. + +Select **Revoke** and confirm to stop clients using the key. Your permissions determine which keys you can revoke. A revoked key can then be removed from the list with **Delete**; its security audit record remains. + +Signing out of a device that uses a pasted key only forgets that local copy. It does not revoke the key for other clients. If a secret was exposed, revoke it, issue a replacement, and update every authorized client that used it. + +## Keep key types separate + +Workspace keys connect to Synthetic Sciences. Provider keys connect to OpenAI, Anthropic, Google, or another provider. Shared provider connections have their own [workspace controls](/account/shared-connections). None of these keys should appear in a repository, prompt, exported research package, or public issue. diff --git a/src/content/account/api.mdx b/src/content/account/api.mdx new file mode 100644 index 0000000..2910900 --- /dev/null +++ b/src/content/account/api.mdx @@ -0,0 +1,39 @@ +--- +title: "API boundaries" +description: "Choose the OpenScience local API or the account service without relying on retired Atlas contracts." +--- + +## Choose the correct service + +| Need | Interface | +| --- | --- | +| OpenScience sessions, operations, events, files, and local compute state | [OpenScience local API](/openscience/api), [server hosting](/openscience/server-hosting), and [TypeScript SDK](/openscience/extensions). | +| Account access, workspace membership, Wallet, private Graphs, and Ascent entitlement | The authenticated Synthetic Sciences account service used by the dashboard. | +| An old Atlas command or integration | Check [compatibility status](/account/compatibility); retained code does not establish a supported public endpoint. | + +Do not send a workspace key to a model provider or a provider key to the account service. Browser account actions and workspace keys can have different permissions; not every endpoint accepts every credential type. + +## Account route families + +The current dashboard uses these route families. They describe service boundaries, not a promise that all legacy Atlas routes remain available or that every route accepts workspace-key authentication. + +| Family | Current examples | +| --- | --- | +| Account context | `GET /api/account-context`, `GET /api/auth/status`. | +| Workspaces | `/api/organizations`, with workspace-specific members, keys, billing, and usage routes. | +| Account usage | `GET /api/credits/usage`. | +| Private nodes | `GET /api/nodes`, `GET /api/nodes/{node_id}`, and staged create/update/commit operations. | +| Sharing | `GET /api/sharing/{node_id}` and authorized sharing mutations. | +| Export/import | `POST /api/export/subgraph`, `POST /api/import/subgraph`. | +| Ascent | `GET /api/ascent/access`, `POST /api/ascent/access/request`, `GET /api/ascent/entitlement`. | +| Trace privacy | `/api/v1/telemetry` with authenticated consent and deletion operations. | + +There is no single `/api/v1` prefix for all dashboard routes. Older docs that combine local CLI pseudo-commands and HTTP endpoints should not be used to build a new client. + +## Integrate with explicit contracts + +Verify the current route, request schema, authentication scope, and response shape for the operation you need. Use current revisions for graph writes and handle conflicts by re-reading the record. Where an operation defines idempotency, retain its identifier across uncertain retries; do not assume an arbitrary header makes every write idempotent. + +Usage APIs accept inclusive `since` and exclusive `until` timestamps. The dashboard converts inclusive UTC dates into those bounds and limits its report range to 366 days. Keep that distinction when comparing a custom report with a CSV export. + +Account billing, access, and privacy changes require their supported authorization flow. An ordinary model-access key does not confer administrator permissions. For a new automation, start with the documented [OpenScience CLI](/openscience/commands) or SDK, and keep account mutations in their supported dashboard workflow unless you have verified the integration contract. diff --git a/src/content/account/ascent.mdx b/src/content/account/ascent.mdx new file mode 100644 index 0000000..b23a6c3 --- /dev/null +++ b/src/content/account/ascent.mdx @@ -0,0 +1,26 @@ +--- +title: "Ascent access" +description: "Request access, check your account's status, and download an approved build when available." +--- + +Open [Ascent](https://app.syntheticsciences.ai/ascent) while signed in. Access is tied to the account that requests it; an OpenScience installation, Ace balance, or workspace membership does not by itself grant Ascent access. + +## Request and check access + +Select **Request access** to submit a request from the current account. The page displays the current state: + +| State | Next step | +| --- | --- | +| Request access | Submit a request from the account you intend to use. | +| Request received | The request is pending review; use **Check status** later. | +| Access ready | Your entitlement is approved. Download the build if a download is available. | +| Access unavailable | The account is not authorized or its entitlement could not be verified; check status or retry as offered. | +| Could not check access | Retry the check after resolving the connection problem. | + +Approval does not guarantee that a build is currently available. An approved page can explain that the download will appear when a build is ready. + +## Download and sign in + +Use **Download Ascent** only when it appears on the approved account's page. Sign in to the client with the same account. A copied download link or a teammate's approval does not grant your account an entitlement. + +For account issues, use [Troubleshooting](/account/troubleshooting). OpenScience can be installed independently through its [installation guide](/openscience/installation). diff --git a/src/content/account/authentication.mdx b/src/content/account/authentication.mdx new file mode 100644 index 0000000..007a0d7 --- /dev/null +++ b/src/content/account/authentication.mdx @@ -0,0 +1,38 @@ +--- +title: "Authentication and devices" +description: "Understand browser sign-in, workspace-bound keys, device approval, and sign-out." +--- + +## Browser and device sign-in + +The dashboard uses your browser session. OpenScience uses an approved device connection or a workspace API key. Approve only a sign-in request you initiated, check the account and workspace, and return to OpenScience after approval. + +```bash +openscience login +openscience status +openscience devices +``` + +The `devices` command shows this installation's sign-in. Manage other devices through your account settings. `openscience login --no-browser` supports approval from a browser on another machine. + +## Funding scope + +A device approval selects a funding workspace. In OpenScience, **Customize → General → Funding workspace → Switch workspace** starts a new approval flow. Changing only the dashboard workspace does not change the app's existing selection. + +A workspace API key is pinned to the workspace that issued it. A Personal key stays Personal even if you later select a team in the browser. New managed requests must have access to their selected workspace; they do not silently spend a different Wallet when access or funds are missing. + +## Sign out + +```bash +openscience logout +``` + +For browser sign-in, the app attempts to revoke its device credential and removes local access. If remote revocation fails, remove the device through account settings. A pasted API key is forgotten locally without being revoked; revoke it in **API Keys** to stop other clients using it. + +Sign-out preserves local research and separately connected provider credentials. It stops this device's account trace uploads, but does not delete already stored account data or disable auto reload. See [Privacy](/account/privacy) and [Billing](/account/billing). + +## Recover a connection + +Check `openscience status` after browser approval. If the workspace is missing, verify your account, invitation, and membership. If a key is revoked, create and connect a replacement. Do not paste secrets into support issues or screenshots. + +For a configured installation, an account-service outage does not reroute or bill your direct provider and local model connections through Ace. Managed access and shared credentials still require the corresponding service and authorization. diff --git a/src/content/account/billing.mdx b/src/content/account/billing.mdx new file mode 100644 index 0000000..92a08fb --- /dev/null +++ b/src/content/account/billing.mdx @@ -0,0 +1,52 @@ +--- +title: "Wallet and billing" +description: "Fund Ace, distinguish purchased and promotional credit, and control optional automatic charges." +--- + +Ace is pay as you go. Enabling access costs $0 and does not create a subscription or authorize automatic card charges. Purchased funds and valid promotional credits can fund managed requests without a saved card. + +## What is charged + +Managed inference and enhanced research search can debit the selected workspace's credit. Your own provider keys, supported subscriptions, local models, and user-owned compute use their own access and billing. Synthetic Sciences does not currently sell managed compute leases or host general-purpose agent jobs. + +OpenScience shows **Wallet**, **Your key**, **Subscription**, or **Local** beside classified model routes. Separately requested search and image services can have their own funding route. See [Ace](/openscience/ace), [Research search](/openscience/research-search), and [Image generation](/openscience/image-generation). + +## Purchased funds and promotional credit + +The Wallet is purchased balance. Promotional credit is a separate benefit with its original expiry; it is not purchased cash. The account must still have access, sufficient credit, and room under applicable usage limits. + +Choose the intended workspace, open **Billing**, then use the Wallet funding control to enter an amount and **Continue to Stripe**. Review the Wallet value, separate processing fee, and total charge before paying. The processing fee does not become Wallet value. + +## Optional auto reload + +| Control | Behavior | +| --- | --- | +| Reload amount | Fixed $20 of purchased Wallet value. | +| Trigger | Purchased funds below $5. | +| Payment | Saved card, with the separately disclosed processing fee. | +| Authorization | Separate explicit opt-in in Billing. | +| Monthly charge limit | Caps automatic card charges; must cover at least one complete reload charge. | + +Open **Billing → Auto reload → Set up**, review the displayed terms and card, set a monthly charge limit, then select **Turn on auto reload**. The amount and trigger are read-only; the charge limit is configurable. A monthly managed-usage limit is a separate control. + +Use **Manage → Turn off** to disable future reloads. Turning Ace access off also stops new managed work and reloads while preserving funds, cards, invoices, and limits. An already submitted charge or reserved request can still reconcile. + +Switching OpenScience to **Keys & subscriptions**, closing the app, or signing out does not cancel reload authorization. Manage it explicitly in Billing. + +## Rates and final charges + +Read **Customize → Models → Rates and limits** for the selected model and speed. Direct serving routes add no funding or service fee. An OpenRouter route includes its funding fee once in the displayed Wallet rate; do not add it again. Card processing is separate from model pricing. + +Input, output, cached input, cache writes, and long-context tiers can have different prices. Fixed schedules show exact rates; variable input/output rates say **Up to**, with cached prices shown as estimates. Standard and Fast can have different hosts and rates. The current catalog determines availability and disclosures. + +A temporary reservation is not the final charge. Once usage is confirmed, the charge is settled and unused reserved funds released. A failed or interrupted request may have completed paid work; inspect the result and its receipt before retrying. + +## Receipts and usage + +Billing shows recent payments and available hosted receipt links. Use **Manage in Stripe** for the saved payment method and billing details. A payment receipt records Wallet funding and its fee; [Usage reports](/account/usage) record model or service activity. They are different records. + +If a reload is in progress or being reconciled, wait for the payment status rather than creating duplicate payments. If the card was declined, review the displayed reason and update the card. Keep the workspace, payment or request identifier, time, and amount when contacting support. + +## Retired plans + +New subscriptions, Ace+, scheduled monthly top-ups, plan quotas, managed compute leases, and public agent jobs are retired. Existing transition records, paid-through access, and balances are preserved under the account's migration policy. Do not follow older Atlas quota or compute-purchase instructions. diff --git a/src/content/account/compatibility.mdx b/src/content/account/compatibility.mdx new file mode 100644 index 0000000..abdaf9a --- /dev/null +++ b/src/content/account/compatibility.mdx @@ -0,0 +1,30 @@ +--- +title: "Atlas compatibility and migration" +description: "Find current workflows when an older Atlas page, command, package, or bookmark no longer applies." +--- + +Atlas is retired as a public website and package offer. Use OpenScience for active research work and the Synthetic Sciences dashboard for account services and private Graphs. Do not install the retired Atlas package as a prerequisite for either. + +## Replace older workflows + +| Older guide or feature | Current path | +| --- | --- | +| Atlas installation or agent onboarding | [Install OpenScience](/openscience/installation) and [connect your account](/account/quickstart). | +| Atlas web application | [Synthetic Sciences dashboard](https://app.syntheticsciences.ai). Old `/atlas`, `/install`, `/guide`, and `/docs` app bookmarks redirect to OpenScience. | +| Research graph, nodes, and evidence | [Private Graphs](/account/graphs) and [Evidence and portability](/account/evidence). | +| Atlas skills or research-loop recipes | [OpenScience skills](/openscience/skills), [experiment tracking](/openscience/experiment-tracking), and [autoresearch](/openscience/autoresearch). | +| Managed compute leases and hosted jobs | Connect [your own compute](/openscience/compute) and use [jobs](/openscience/jobs). These are not account-hosted compute offers. | +| Quotas, Ace+, or a new monthly plan | [Prepaid Ace and optional auto reload](/account/billing). | +| Atlas MCP-era setup | Use the current [OpenScience connectors](/openscience/connectors) or [local API](/openscience/api) for supported integrations. | + +## Existing installations and records + +The `@synsci/atlas` package name, `atlas` command, some `thk_` keys, and historical API or database identifiers can remain in retained compatibility code and records. Their presence does not mean every old command is active or every old endpoint is mounted. + +Keep existing research exports and record the version and exact command when diagnosing an old installation. Do not assume a broad command registry proves server availability. Use the current dashboard for account changes and verify the supported interface before adapting automation. + +Existing balances, paid-through access, and historical billing records are preserved under the migration policy. A retired subscription or quota description is not an offer to purchase a new plan. + +## Preserve research before changing tools + +Keep copies of source files, graph exports, run records, and evidence. OpenScience session imports and Graphs imports are different formats; neither is a universal importer for all historic Atlas data. Review [Evidence and portability](/account/evidence) and [OpenScience handoffs](/openscience/team-workflows), then verify a small restored sample before depending on a migration. diff --git a/src/content/account/docs.json b/src/content/account/docs.json new file mode 100644 index 0000000..ee784d4 --- /dev/null +++ b/src/content/account/docs.json @@ -0,0 +1,75 @@ +{ + "name": "Synthetic Sciences", + "navigation": { + "tabs": [ + { + "tab": "Guides", + "groups": [ + { + "group": "Get started", + "pages": [ + "index", + "quickstart", + "authentication" + ] + }, + { + "group": "Workspaces and access", + "pages": [ + "workspaces", + "api-keys", + "shared-connections" + ] + }, + { + "group": "Ace and your account", + "pages": [ + "billing", + "usage", + "privacy", + "ascent" + ] + }, + { + "group": "Private research", + "pages": [ + "graphs", + "evidence", + "sharing" + ] + }, + { + "group": "Reference and help", + "pages": [ + "api", + "compatibility", + "troubleshooting" + ] + } + ] + } + ], + "global": { + "anchors": [ + { + "anchor": "Dashboard", + "href": "https://app.syntheticsciences.ai" + }, + { + "anchor": "Get OpenScience", + "href": "https://openscience.sh/download" + }, + { + "anchor": "Privacy policy", + "href": "https://openscience.sh/privacy" + } + ] + } + }, + "navbar": { + "primary": { + "label": "Open dashboard", + "href": "https://app.syntheticsciences.ai" + } + } +} diff --git a/src/content/account/evidence.mdx b/src/content/account/evidence.mdx new file mode 100644 index 0000000..a6a436c --- /dev/null +++ b/src/content/account/evidence.mdx @@ -0,0 +1,35 @@ +--- +title: "Evidence and portability" +description: "Attach research evidence, preserve provenance, and export records without assuming every file is included." +--- + +## Keep evidence with the claim + +Use a node's **evidence** section to inspect and attach the material supporting its result. Keep the original data or an authorized retrieval reference, the analysis code, exact commands, environment versions, metrics, and final figures. Record missing evidence explicitly rather than implying it was checked. + +An attachment, repository reference, and external experiment link have different retention and access properties. Verify that a collaborator can actually open the evidence before calling the handoff complete. + +## Record a reproducible run + +At minimum, preserve: + +- Objective, hypothesis, and planned success criterion. +- Dataset identifier or checksum, preprocessing, split, seed, and environment. +- Exact command, code commit, resource budget, start and end state. +- Metrics, output paths, logs, failed checks, and interpretation. + +Execution takes place in your tools and compute environment. Saving a graph record does not start a managed cloud job. See [OpenScience jobs](/openscience/jobs), [remote compute](/openscience/remote-compute), and [experiment tracking](/openscience/experiment-tracking). + +## Export records + +Use the node's **export as json**, **export as markdown**, or **export as pdf** controls. Structured subgraph exports preserve research records and relationships; readable summaries are useful for review. Inspect the selected nodes and descendant scope before exporting. + +Do not assume a graph export embeds every referenced dataset, remote artifact, repository checkout, or provider log. Retain those files separately, document access requirements, and inspect the export before deleting the source records. + +The account API includes subgraph export and import operations for integrations; see [API boundaries](/account/api). Use the current request contract and verify a small imported sample. Importing graph records is different from importing an [OpenScience conversation](/openscience/sessions). + +## Prepare a handoff + +Include a README describing the research question, graph scope, file locations, required access, exact reproduction steps, completed checks, and unresolved issues. Remove credentials and material the recipient may not access. Keep claims traceable to their evidence and distinguish an original result from your reproduction. + +For local research packages, follow [Share and hand off research](/openscience/team-workflows). diff --git a/src/content/account/graphs.mdx b/src/content/account/graphs.mdx new file mode 100644 index 0000000..922ed30 --- /dev/null +++ b/src/content/account/graphs.mdx @@ -0,0 +1,42 @@ +--- +title: "Private Graphs" +description: "Keep research claims, hypotheses, results, and decisions connected to their evidence." +--- + +Open [Graphs](https://app.syntheticsciences.ai/graphs) in the dashboard to view research you own or can access. Graphs preserve research relationships independently of an OpenScience conversation. They are not a cloud copy of every local project. + +## Understand a node + +A node has an identity, title, summary, content, kind, lifecycle, outcome, and revision. It can also record a hypothesis, insights, parent relationships, evidence, tags, and repository provenance. Parent and child relationships show how one research step builds on another. + +| Information | Record | +| --- | --- | +| Claim or hypothesis | The statement, assumptions, expected observations, and what would disconfirm it. | +| Experiment | The method, inputs, evaluation metric, success criterion, and resource constraints. | +| Result | The observed outcome, uncertainty, evidence, and failed or incomplete checks. | +| Decision | The chosen next step, rationale, and alternatives considered. | +| Code provenance | Repository URL, branch, and exact commit when available. | + +Record an observation separately from your interpretation. A saved node or successful commit does not validate a scientific claim by itself. + +## Stage and commit research + +Draft nodes use the staged lifecycle. Edit the title, summary, content, and applicable research fields before committing. The node's commit checklist identifies missing fields such as kind, outcome, summary, hypothesis, insight, and attached artifacts or an explicit reason for no artifacts. Requirements depend on the node kind and outcome. + +Review the evidence and complete the checklist before committing. If a save reports a revision conflict, refresh the node and compare the latest record before retrying; do not blindly overwrite another update. + +## Continue and compare branches + +Create a child node to record a follow-up. Keep alternative approaches in separate branches so the original result and its evidence remain understandable. Record failed and inconclusive attempts as well as successful ones; they explain why you selected the next step. + +For a comparison, use the same data revision, evaluation split, metric definition, and resource budget. Link each candidate's outputs and record why you preferred one. OpenScience can help prepare [experiment records](/openscience/experiment-tracking) and [reproduction packages](/openscience/reproduction); those files are not automatically Graphs records. + +## Evidence, tags, and history + +Open a node to inspect its evidence, tags, repository provenance, and audit history. Follow source references before reusing a claim. An external URL can become unavailable or require separate access even when the node itself is accessible. + +Use [Evidence and portability](/account/evidence) for attachments and exports, and [Graph sharing](/account/sharing) for collaborator access. + +## Delete carefully + +Read the deletion confirmation and affected scope before deleting a node or branch. Parent relationships and descendant operations can affect more than the selected record. Keep an export and original evidence when retention matters; do not assume deletion can be undone. diff --git a/src/content/account/index.mdx b/src/content/account/index.mdx new file mode 100644 index 0000000..1121737 --- /dev/null +++ b/src/content/account/index.mdx @@ -0,0 +1,32 @@ +--- +title: "Synthetic Sciences account" +description: "Manage OpenScience access, Ace, workspaces, private Graphs, and Ascent from your dashboard." +--- + +The [Synthetic Sciences dashboard](https://app.syntheticsciences.ai) manages your account, workspace access, and managed services. OpenScience is the research workbench; the dashboard supplies account access, Ace funding, shared connections, private Graphs, and Ascent access requests. + +## Start with your task + +| You want to | Read | +| --- | --- | +| Install the workbench and run research | [OpenScience quickstart](/openscience/quickstart). | +| Sign in or connect another device | [Account setup](/account/quickstart) and [Authentication](/account/authentication). | +| Use managed models without individual provider keys | [Ace](/openscience/ace) and [Wallet and billing](/account/billing). | +| Review activity or export costs | [Usage reports](/account/usage). | +| Work with a team | [Workspaces and members](/account/workspaces) and [Shared connections](/account/shared-connections). | +| Connect a runner with a workspace key | [API keys](/account/api-keys). | +| Preserve research relationships and evidence | [Private Graphs](/account/graphs) and [Evidence and portability](/account/evidence). | +| Request Ascent | [Ascent access](/account/ascent). | +| Review data sharing | [Privacy and data](/account/privacy). | + +## Account access and model access + +OpenScience's first-run setup requires an account. Ace is optional. Your own provider keys, eligible provider subscriptions, local models, and user-owned compute remain direct connections. Signing in does not turn them into managed Wallet usage. + +Ace can use purchased funds or valid promotional credits without a saved card. Enabling access costs $0. Automatic card reloads require separate consent. There is no current subscription, Ace+ tier, plan quota, managed compute lease, or hosted general-purpose agent-job offer. + +## Existing Atlas users + +Atlas is retired as a public website and package offer. Private research Graphs remain in the dashboard. Retained package names, old key formats, and selected service routes are compatibility identifiers, not a new installation path. Use [Atlas compatibility and migration](/account/compatibility) if you followed an older guide. + +Old documentation URLs redirect to current guides. The active workbench documentation remains under [OpenScience](/openscience/index). diff --git a/src/content/account/privacy.mdx b/src/content/account/privacy.mdx new file mode 100644 index 0000000..5017169 --- /dev/null +++ b/src/content/account/privacy.mdx @@ -0,0 +1,30 @@ +--- +title: "Account privacy and data" +description: "Understand trace sharing, private research, usage visibility, and deletion boundaries." +--- + +## Local work and account data + +OpenScience project files and saved conversations live in its local storage and connected folders. Signing in provides account access and supported shared connections; it is not a complete backup or automatic file-sharing service. + +The selected model and online tools receive the context required for their requests. A local model keeps model inference local, but online search, connectors, remote compute, and trace sharing can still send data off the device. See [OpenScience privacy](/openscience/privacy). + +## Session traces + +Signed-in OpenScience installations share session traces by default unless a prior opt-out applies. They can include prompts, model context and responses, provider-visible reasoning, tool inputs and outputs, searches, errors, and reported usage. Known credentials are redacted, but private research can remain in these records. + +In OpenScience, open **Customize → General → Data & privacy → Share session traces** to stop uploads from that device and discard queued and rejected records. Account preferences can disable sharing across devices or exclude user-owned routes. Device settings cannot override an account opt-out. + +Trace delivery and the account usage charts are different records. Missing trace content does not establish that no paid request occurred, and a direct-provider usage estimate is not a Wallet debit. + +## Graph and workspace visibility + +Graphs are private to their owners and explicitly authorized collaborators. Public discovery and anonymous graph reads are not a default supported sharing path. Membership in a funding workspace does not automatically expose another member's research. + +Authorized workspace usage viewers can see managed totals and member attribution. That reporting permission does not grant access to the member's private prompts, files, or Graphs. + +## Opt out or delete + +Turning off future sharing and deleting stored account data are separate actions. Use the privacy controls and review the current [privacy policy](https://openscience.sh/privacy) for retention and deletion scope. Trace-data deletion does not delete local project files, revoke external provider keys, cancel card reload consent, or erase financial records. + +Export data you need before deleting it. Inspect exports before sharing, because they can contain research content and source references. Use private support for account data issues; keep secrets and private datasets out of public bug reports. diff --git a/src/content/account/quickstart.mdx b/src/content/account/quickstart.mdx new file mode 100644 index 0000000..f37c1a0 --- /dev/null +++ b/src/content/account/quickstart.mdx @@ -0,0 +1,39 @@ +--- +title: "Account setup" +description: "Sign in, choose a workspace, connect OpenScience, and verify the first request." +--- + +## 1. Sign in + +Open [app.syntheticsciences.ai](https://app.syntheticsciences.ai) and complete the available sign-in flow. Use the same account when accepting a team invitation or requesting Ascent access. + +## 2. Choose a workspace + +Open the [workspace selector](https://app.syntheticsciences.ai/workspaces). Use Personal for your own funding and connections, or choose a team you belong to. Each workspace has its own Wallet, members, permissions, and keys. + +A workspace in the dashboard supplies funding and shared access. It does not automatically synchronize your local research folder or conversations. See [Workspaces and members](/account/workspaces). + +## 3. Connect OpenScience + +Install the [OpenScience app](/openscience/installation). During first-run setup choose **Continue with Synthetic Sciences**, approve the device in your browser, and return to the app. For terminal access: + +```bash +openscience login +openscience status +``` + +On a machine without a browser, `openscience login --no-browser` prints approval instructions. A [workspace API key](/account/api-keys) is another option. + +## 4. Choose how to run models + +- **Ace:** confirm access and purchased or promotional credit in the chosen workspace. Add funds if needed. A saved card and auto reload are optional. +- **Keys & subscriptions:** connect your provider access in OpenScience. The provider bills those model requests directly. +- **Local models:** connect your running endpoint in OpenScience. Model inference uses your hardware. + +Read [Wallet and billing](/account/billing) before enabling automatic reload. Changing model access in OpenScience does not revoke an existing reload authorization. + +## 5. Verify a small task + +Open an OpenScience project and ask it to summarize a small file you can check. Confirm the selected model and its funding label, inspect the result, then review **Customize → Usage** or the dashboard's **Usage** page. + +Before using private material, review [Privacy and data](/account/privacy). For account failures, use [Troubleshooting](/account/troubleshooting). diff --git a/src/content/account/shared-connections.mdx b/src/content/account/shared-connections.mdx new file mode 100644 index 0000000..4f03fe5 --- /dev/null +++ b/src/content/account/shared-connections.mdx @@ -0,0 +1,33 @@ +--- +title: "Shared connections" +description: "Let authorized members use workspace provider and service connections without confusing them with personal keys." +--- + +## Connect at the right scope + +Use the selected workspace's shared-credentials page when you intend to provide a connection to the team. Managing these connections requires the corresponding workspace permission. A provider key connected locally in OpenScience remains personal; it is not automatically published to the workspace. + +Choose the supported provider or service, enter the required fields, and follow its verification flow. A saved credential does not guarantee access to every model, resource, or paid feature that provider offers. + +## Refresh OpenScience + +Confirm the device's **Funding workspace**, then select **Customize → General → Sync now**, or run: + +```bash +openscience sync +openscience status +``` + +Your saved local provider key, explicit environment key, or provider sign-in takes precedence over a shared connection. If the app continues using a personal credential, inspect those sources before replacing the shared key. + +## Billing and scope + +A shared provider connection uses that provider's access and terms. It is distinct from managed Ace usage billed to the Wallet. The model picker and request's funding route help identify the connection in use. A paid search or image request can use a different route from the chat model. + +Workspace connections do not upload or synchronize every research folder. Use [OpenScience handoffs](/openscience/team-workflows) for files and [Graphs](/account/graphs) for explicit research sharing. + +## Replace or remove a connection + +Check which devices or workflows depend on a shared credential before removing it. Update the connection, verify it, and refresh affected clients. Removing a stored credential does not revoke it at the original provider; use the provider's controls when revocation is required. + +If a member cannot use it, check their workspace membership, connection permissions, selected funding workspace, and provider error. Do not share the raw secret in a support message or invitation. diff --git a/src/content/account/sharing.mdx b/src/content/account/sharing.mdx new file mode 100644 index 0000000..aeb6ba9 --- /dev/null +++ b/src/content/account/sharing.mdx @@ -0,0 +1,26 @@ +--- +title: "Graph sharing" +description: "Understand private ownership, explicit collaborator permissions, and the limits of workspace membership." +--- + +## Private by default + +Graphs are accessible to their owners and explicitly authorized collaborators. Public discovery and anonymous graph reads are disabled by default. Do not use an old public Atlas link as evidence that a graph is publicly available. + +The node's sharing information shows ownership, effective permissions, and available collaborator controls. Collaboration can be unavailable under the current service policy; only use the controls actually offered to your account. + +## Check permissions + +Viewing, writing, and administering sharing are different permissions. A collaborator who can read a node does not necessarily have permission to edit it or add another collaborator. The server determines access on each request. + +When sharing is available, choose the intended people and roles, review the node or batch scope, and verify access from the recipient's account. Do not assume all ancestors, descendants, external files, or repository content inherit the same access. + +## Keep funding separate + +Joining a [workspace](/account/workspaces) supplies the access allowed by that workspace's funding and connection policy. It does not automatically publish local OpenScience research or grant access to every member's private graph. Usage reports can show member spend without exposing research content. + +## Revoke and export deliberately + +Use the permitted sharing controls to remove a collaborator or narrow access. A revocation cannot recall files or exports a recipient already downloaded. Review the material before sharing and preserve the necessary consent and data-use restrictions with the research package. + +See [Evidence and portability](/account/evidence) for export scope and [Privacy](/account/privacy) for account data controls. diff --git a/src/content/account/troubleshooting.mdx b/src/content/account/troubleshooting.mdx new file mode 100644 index 0000000..9ef6676 --- /dev/null +++ b/src/content/account/troubleshooting.mdx @@ -0,0 +1,40 @@ +--- +title: "Account troubleshooting" +description: "Resolve sign-in, membership, funding, usage, and Ascent access problems." +--- + +## Device approval does not finish + +Return to OpenScience after browser approval and run `openscience status`. Verify the account and workspace you approved. For a machine without a browser, use `openscience login --no-browser`. Do not approve an unrelated request or share the device secret. + +## Workspace not found + +Refresh [workspaces](https://app.syntheticsciences.ai/workspaces), check the signed-in account, and confirm the invitation was accepted. Membership can be removed after a page loads. A browser workspace switch does not change a device or API key's existing funding scope. + +## Ace cannot start a request + +Check the selected funding workspace, managed-access permission, valid purchased or promotional credit, and applicable monthly limits. A saved card alone is not credit or auto-reload consent. Personal provider and local routes have separate credentials and availability. + +If auto reload is enabled, inspect Billing for a pending payment, card decline, missing payment method, or reached monthly charge limit. Resolve the displayed cause before repeatedly retrying a paid task. + +## Payment is pending or declined + +Billing reports whether a reload is in progress, with the bank, or being reconciled. The Wallet updates when the payment is confirmed. For a declined card, review the reason and use **Update card** or **Manage in Stripe**. A submitted charge can still settle after auto reload is disabled. + +Do not create another payment just because a receipt or balance update is delayed. Keep the workspace, amount, time, and payment identifier for private support. + +## Usage looks different + +Compare the same UTC dates, model, source, and funding workspace. Local reports reflect saved device conversations; account reports reflect received records; workspace permissions can restrict totals. Reservations, provider estimates, settled charges, and card-funding receipts are distinct. See [Usage reports](/account/usage). + +## Shared connection is unavailable + +Verify workspace membership and the device's funding selection, then run `openscience sync`. Ask an authorized administrator to check the shared connection. A local key or environment variable may take precedence over that shared connection. + +## Ascent has no download + +Check the signed-in account's [Ascent page](https://app.syntheticsciences.ai/ascent). Pending review, denied access, an unverified entitlement, and an approved account waiting for a build are different states. Follow the page's current status; Wallet funding does not grant access. + +## Ask for help + +Include the affected interface, installed OpenScience version, steps, time, workspace, exact error, and request identifier when available. Share only the minimum evidence needed. Use private support for payments or account data and [OpenScience issues](https://github.com/synthetic-sciences/openscience/issues) for a reproducible product bug with private material removed. diff --git a/src/content/account/usage.mdx b/src/content/account/usage.mdx new file mode 100644 index 0000000..534b854 --- /dev/null +++ b/src/content/account/usage.mdx @@ -0,0 +1,32 @@ +--- +title: "Usage reports" +description: "Inspect account and workspace activity, filter UTC dates and models, and export matching totals." +--- + +Open [Usage](https://app.syntheticsciences.ai/usage) for account activity, or choose a workspace and open its **Usage** page for workspace-funded activity. + +## Select the report scope + +Account usage distinguishes managed Wallet charges from reported API-key, local, ChatGPT, subscription, custom, and unclassified activity. User-owned costs are estimates and do not become Wallet charges. Subscription fees and your hardware costs are not included. + +Workspace reports show managed activity. Owners and members with usage-view permission see workspace totals and **Usage by member**. Other members see their own requests and spend in that workspace. A usage permission does not grant access to private research content. + +The desktop's **Customize → Usage** also reports saved local conversations across projects on that device. Its user-owned records can differ from the dashboard's reported account activity, especially when trace sharing is disabled. See [OpenScience usage](/openscience/usage). + +## Filter dates, source, and model + +Choose a date preset or custom **From** and **To** dates. Both dates are inclusive in UTC; the maximum range is 366 days. Choose the available source and model filters. Review the summary, daily activity chart, and model totals for that selection. + +Use **Refresh** after activity completes. A loading failure or permission error does not establish that no usage occurred. Confirm the account and workspace before comparing reports. + +## Export CSV + +Select **Export CSV** below the report. It exports all matching daily model/endpoint totals, including token details, USD cost, and billed or estimated cost basis. It is independent of the recent-request history's 50-row limit. + +The export is aggregated activity, not a conversation export or payment receipt. For managed records, input/output already include reported cache and reasoning detail. Preserve the provided total instead of recomputing it by adding every detail column. Retain cost precision when analyzing exports. + +## Reconcile with billing + +Use [Billing](/account/billing) for purchased funds, promotional balances, reservations, settled charges, and card receipts. Card payments can include processing fees and occur on different dates from model usage. Direct provider estimates should be reconciled with that provider's billing. + +For unexplained differences, keep the UTC date range, model, selected workspace, relevant CSV rows, and request identifier if available. Do not send prompts or secrets when a usage identifier is sufficient. diff --git a/src/content/account/workspaces.mdx b/src/content/account/workspaces.mdx new file mode 100644 index 0000000..4fb1dca --- /dev/null +++ b/src/content/account/workspaces.mdx @@ -0,0 +1,36 @@ +--- +title: "Workspaces and members" +description: "Choose Personal or team funding, invite members, and manage access and spending permissions." +--- + +## Choose a workspace + +Use the [workspace selector](https://app.syntheticsciences.ai/workspaces) to choose Personal or a team you belong to. Each workspace has its own Wallet, access policy, keys, shared connections, and usage view. Personal is your own funding context; team access is governed by membership. + +Switching in the dashboard changes the pages you are viewing. An OpenScience device keeps its approved funding selection until you switch it in **Customize → General → Funding workspace**. A workspace API key stays bound to its issuing workspace. + +## Invite and manage members + +Members with management permission can open **Members → Invite member**, enter the recipient's address, and select the available role and spending policy. Share a returned one-time invitation link only with the invited person. The recipient must accept using the intended account. + +The Members page shows current members and pending invitations. Administrators can update permitted roles, revoke pending invitations, or remove members. Ordinary role assignment offers **Member** and **Admin**; ownership transfer is a separate settings action. Legacy roles can appear as read-only transition data. + +Server permissions determine which controls are available. If you lose access while a page is open, refresh the workspace rather than treating previously displayed controls as continuing authorization. + +## Set spending limits + +In Members, use **Limit** to set a member's monthly managed spend ceiling. Blank means no per-member limit; $0 blocks workspace-funded spend. Workspace policy and the available Wallet still apply. + +The member limit, workspace managed-usage limit, and optional auto-reload monthly charge limit serve different purposes. A reload limit caps card funding; it does not grant a member permission to spend. See [Wallet and billing](/account/billing). + +## Shared access is not shared research + +Membership can provide shared model or service credentials and managed usage. It does not automatically publish local OpenScience conversations or files. Private [Graphs](/account/graphs) and explicit collaborator access are separate from funding membership. + +Manage connections in [Shared connections](/account/shared-connections), and create device-specific credentials in [API keys](/account/api-keys). + +## Leave, transfer, or remove access + +Use the workspace Settings and Members controls available to your role. Check the impact before confirming ownership transfer or removal. Revoking membership can remove managed access and shared connections from affected clients; it does not revoke a person's separately owned provider credentials or delete their local project files. + +If a workspace link says **Workspace not found**, refresh the list and verify the signed-in account and membership. Do not create another workspace just to work around a temporary loading failure. diff --git a/src/content/atlas/api-keys.mdx b/src/content/atlas/api-keys.mdx deleted file mode 100644 index 4ae4dd1..0000000 --- a/src/content/atlas/api-keys.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "API keys" -description: "Create, list, rotate, and revoke thk_* keys for agents and CI." -icon: "key-round" ---- - -API keys let agents, scripts, and CI authenticate without the browser flow. Every key is prefixed `thk_`, sent as `Authorization: Bearer `, and managed through `/api/auth/api-keys`. - -## Create a key - -```bash -atlas key:create --name "ci-runner" --expiry-days 90 --format=json -``` - -The full secret is returned **once**. Store it in your secret manager and export it as `ATLAS_API_KEY` where the CLI or API runs. In shared logs, print only the prefix. - -## Lifecycle - -```bash -atlas key:list --active-only --format=json -atlas key:rotate --key-id key_... --format=json -atlas key:delete --key-id key_... --yes -``` - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `key:create` | `POST` | `/auth/api-keys` | Create a named key; prints the secret once. | -| `key:list` | `GET` | `/auth/api-keys` | List key ids, names, prefixes, and timestamps. | -| `key:rotate` | `POST` | `/auth/api-keys/{key_id}/rotate` | Issue a new secret while keeping the key record. | -| `key:delete` | `DELETE` | `/auth/api-keys/{key_id}` | Revoke a key. Requires `--yes`. | - -The `key:list` view shows a `PREFIX` column (for example `thk_856dc108`) so you can match a key to its usage without ever seeing the secret again. - -## Use a key - -```bash -export ATLAS_API_KEY="thk_..." -atlas whoami --format=json - -curl -H "Authorization: Bearer $ATLAS_API_KEY" \ - https://app.syntheticsciences.ai/api/v1/auth/status -``` - -## Good hygiene - -- Name keys after where they run (`ci-runner`, `lab-box`, `notebook`) so rotation is obvious. -- Set `--expiry-days` for short-lived automation. -- Rotate instead of sharing: `key:rotate` invalidates the old secret immediately. -- Never commit a `thk_*` secret or print it into an agent transcript. diff --git a/src/content/atlas/authentication.mdx b/src/content/atlas/authentication.mdx deleted file mode 100644 index 9c02baa..0000000 --- a/src/content/atlas/authentication.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Authentication" -description: "Browser login, thk_* API keys, local profiles, and config resolution." -icon: "key-round" ---- - -Atlas authenticates two ways: an interactive **browser login** for humans, and **`thk_*` API keys** for agents, scripts, and CI. Both resolve to an Atlas API key sent as `Authorization: Bearer `. - - -The legacy MCP-era pairing and token-exchange flows are retired and now return `HTTP 426 Upgrade Required`. Use `atlas login` or a `thk_*` API key. There is no device-pairing step. - - -## Browser login - -```bash -atlas login -atlas whoami --format=json -atlas logout -``` - -`login` starts a localhost callback, opens the Atlas approval page, redeems a one-time token, and writes an API key to the active profile (file mode `0600`). `logout` removes the stored credential for the active profile. - -## API keys - -For agents and automation, mint a key and pass it through the environment: - -```bash -atlas key:create --name "ci-runner" --format=json -export ATLAS_API_KEY="thk_..." -atlas whoami --format=json -``` - -Keys are prefixed `thk_` and the full secret is shown once. Manage them with `key:create`, `key:list`, `key:rotate`, and `key:delete` (backed by `/api/auth/api-keys`). See [API keys](/atlas/api-keys) for the full lifecycle. - -Call the API directly with the same key: - -```bash -curl -H "Authorization: Bearer $ATLAS_API_KEY" \ - https://app.syntheticsciences.ai/api/v1/auth/status -``` - -## Config resolution - -The CLI resolves the API key in this order: - -1. `--api-key ` -2. `ATLAS_API_KEY` -3. the active profile written by `atlas login` -4. root config fallback - -Useful environment variables: - -| Name | Purpose | -| --- | --- | -| `ATLAS_API_KEY` | Override the stored API key for one invocation. | -| `ATLAS_BASE_URL` | Point at a non-production API base. | -| `ATLAS_CLI_CONFIG_PATH` | Use an alternate profile config file. | -| `ATLAS_LOGIN_TIMEOUT_MS` | Browser-login wait timeout (default 5 min). | -| `NO_COLOR` / `FORCE_COLOR` | Disable or force ANSI color in pretty output. | - -## Profiles - -Keep more than one account or environment side by side with named profiles: - -```bash -atlas config:list -atlas config:set --name staging --base-url https://staging.example/api/v1 -atlas whoami --env staging --format=json -``` - -| Command | Use | -| --- | --- | -| `config:list` | List local profiles with secrets redacted. | -| `config:show` | Show one profile with secrets redacted. | -| `config:set` | Create or update a profile (base URL, default format, retries, timeout). | -| `config:unset` | Remove a profile. | - -## macOS Keychain - -On macOS you can store the key in the Keychain instead of the config file: - -```bash -echo "thk_..." | atlas secret:set -atlas secret:clear -``` - -## Doctor - -Run `doctor` after install, login, or config changes: - -```bash -atlas doctor --format=json -``` - -It checks the config path, active profile, base URL, backend reachability, auth status when a key is present, and the bundled skills. It is safe to run before login; it simply reports that no key is present. diff --git a/src/content/atlas/billing.mdx b/src/content/atlas/billing.mdx deleted file mode 100644 index 539e88d..0000000 --- a/src/content/atlas/billing.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Billing & credits" -description: "Account credit, source-search and research quotas, and how to read usage." -icon: "credit-card" ---- - -Atlas bills against your account. Most graph, source-indexing, and search operations are included; the metered surfaces are research answers and managed compute. Check **Billing** in the app or read usage from the CLI. - -## Read your usage - -```bash -atlas usage:summary --format=json -``` - -`usage:summary` returns the quota and consumption for the current billing period across the metered surfaces. - -| Quota | Spent by | -| --- | --- | -| `oracle` | `research:ask` and `research:jobs:create` (Oracle-style synthesis over your indexed sources). | -| `deep_research` | The deep-research pipeline (`library:search --mode deep` and deep research jobs). | -| credit | Managed executions (`exec:start`), the managed agent runtime, and managed GPU leases (`compute:up`). | - -## What is metered - -- **Graph operations:** creating nodes, recording runs, comparing, and exporting are included. -- **Source indexing and search:** adding sources, `library:search`, and `library:ask` are included, subject to fair-use limits on source size and count. -- **Research answers:** `research:ask` and research jobs deduct from the `oracle` quota. Deep research deducts from `deep_research`. -- **Managed compute:** `exec:start` and the agent runtime draw account credit. A managed GPU lease created with `compute:up` bills the wallet at pass-through pricing and reconciles actual runtime on `compute:release`. BYOK leases use the connected provider account. - -## Manage billing - -Open the app's **Billing** page to add credit, view invoices, and see plan limits: - -```bash -atlas --open whoami -``` - -Then visit [app.syntheticsciences.ai](https://app.syntheticsciences.ai/atlas) and open **Billing** in the sidebar. - -## Keep automation predictable - -- Run `atlas usage:summary` at the start of an autonomous session and stop when a quota is exhausted. -- Prefer `library:search` (included) over `research:ask` (metered) when a grounded match is enough. -- Use `library:search --mode universal` for routine lookups; reserve `--mode deep` for questions that justify the `deep_research` spend. diff --git a/src/content/atlas/cli-overview.mdx b/src/content/atlas/cli-overview.mdx deleted file mode 100644 index 57d0478..0000000 --- a/src/content/atlas/cli-overview.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "CLI overview & conventions" -description: "The command grammar shared across Atlas graphs, indexed sources, and research workflows: namespaces, verbs, slugs, and output." -icon: "terminal" ---- - -One CLI, `@synsci/atlas`, drives the whole product. Learn the grammar once here; the [CLI & API reference](/atlas/commands) covers graph workflows, while `atlas help --format=json` is the authoritative catalog for source indexing, search, and research commands. - -Every command is a direct HTTP call to `https://app.syntheticsciences.ai/api/v1`, plus a handful of local commands (`login`, `logout`, `doctor`, `config:*`, `secret:*`) that also read or write local config. There is no second hidden surface: `atlas help --format=json` is generated from the same registry that dispatches requests. - -## Naming conventions - -Command names are `namespace:verb`. The rules, as of 0.8.x: - -- **Namespaces are singular nouns.** `node:*`, `label:*`, `key:*`, `secret:*`, `integration:*`, and `project:merge` (not `nodes:`, `labels:`, `keys:`, `secrets:`, `integrations:`, `projects:`). -- **`exec:*` is managed node executions.** `exec:start | list | stop` run and manage executions attached to a node. -- **`compute:*` is the GPU marketplace.** `compute:catalog | up | list | ssh | release` browse the cheapest GPUs across providers, launch a VM, and release it when done. Pricing is pass-through (provider cost plus a small fee); bring-your-own-key providers rank as free. -- **`run:*` is the flight recorder.** `run:record | compare | spool:*` capture and compare experiment results. -- **`*:jobs:*` are async jobs.** `library:jobs:*` and `research:jobs:*` create, stream, and cancel long-running work. -- **`github:reconnect`** is the canonical way to refresh an expired GitHub token. - - -Pre-0.8 names (`nodes:create`, `runs:record`, `labels:assign`, `keys:create`, `research:runs:create`, `github:refresh`, and so on) still work as hidden legacy aliases, so old scripts keep running. Write new scripts, prompts, and docs with the canonical singular names only. This is the one page that lists the aliases; everywhere else uses the canonical form. The full rule set lives in `cli/CONVENTIONS.md` in the Atlas repo. - - -## Slugs and ids - -Four resolver flags accept either a human-readable slug (`able-helm-1359`) or a UUID, and the CLI resolves them before dispatch: - -| Flag | Refers to | -| --- | --- | -| `--project` | A project root node. | -| `--node` | Any node. | -| `--plan` | An `experiment:plan` node. | -| `--hypothesis` | A `hypothesis` node. | - -```bash -atlas node:show --node able-helm-1359 --format=json -atlas brief --project able-helm-1359 --format=json -``` - -## Output formats - -Output is **JSON when piped** and a **pretty terminal view** at a TTY. Force a format with `--format`: - -```bash -atlas node:list # pretty at a terminal -atlas node:list | jq '.nodes[0]' # json automatically when piped -atlas node:list --format=json # force json (always lossless) -``` - -| Format | When | Notes | -| --- | --- | --- | -| `pretty` | TTY default | Per-command views with status glyphs and relative times. | -| `json` | Pipe default | Lossless. Every field, no truncation. | -| `table` | Opt-in | The pretty view without color. | -| `tsv` / `csv` | Opt-in | One row per item; nested objects stringified. | - -Set a sticky default with `atlas config:set --default-format json`. - -## Global flags - -| Flag | Use | -| --- | --- | -| `--format ` | `json`, `tsv`, `csv`, `table`, or `pretty`. | -| `--env ` | Select a stored CLI profile. | -| `--out ` | Write output to a file, or `-` for stdout. | -| `--open` | Open browser-bound URLs where supported. | -| `--yes` | Confirm destructive operations. | -| `--force` | Force a safety-gated operation where supported. | -| `--idempotency-key ` | Stable key for retried writes. | -| `--timeout ` | Per-request timeout. | -| `--no-retry` / `--retry-max ` | Tune transient-error retries. | -| `--debug` | Print structured request debugging. | - -Destructive commands (deletes, revokes, cancels, disconnects, rotation) require `--yes` or `--force`. - -Only genuinely transient failures (`408`, `425`, `5xx`) are retried. Rate-limit (`429`) and conflict (`409`) responses are deliberate, so the CLI surfaces a "wait a moment" / "refetch" message and backs off instead of retrying. - -## Discover commands - -```bash -atlas help # grouped text listing -atlas help run:record # text help for one command -atlas help run:record --schema --format=json # the full request shape -atlas help --format=json # the entire catalog -``` - -The bundled `atlas` skill is the router for agents: it points at the right specialized skill and first command for a task. Run `atlas install` to load it (and the other eight skills) into your coding agent. - -## Where commands live - -| Surface | Namespaces | Reference | -| --- | --- | --- | -| Graphs and experiments | `project:*`, `node:*`, `link:*`, `map:*`, `access:*`, `draft:*`, `label:*`, research-loop verbs, `run:*`, `exec:*`, `compute:*`, `evidence:*`, `repo:*`, `github:*` | [CLI & API reference](/atlas/commands) | -| Indexed sources and research | `library:*`, `research:*`, `usage:summary` | `atlas help library:search` / `atlas help research:ask` | -| Shared | `login`, `logout`, `whoami`, `doctor`, `config:*`, `secret:*`, `key:*`, `account:update`, `install` | This section | diff --git a/src/content/atlas/commands.mdx b/src/content/atlas/commands.mdx deleted file mode 100644 index 687d5ff..0000000 --- a/src/content/atlas/commands.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: "CLI & API reference" -description: "Command and route reference for Atlas graphs, experiments, evidence, compute, and integrations." -icon: "terminal" ---- - -Atlas commands and the `/api/v1` routes behind them. Names are canonical (singular namespaces); pre-0.8 aliases still work but are documented only on the [CLI overview](/atlas/cli-overview). For global flags and output formats, see that page too. - -```bash -atlas help --format=json # the whole catalog -atlas help run:record --schema --format=json # one command's request shape -``` - -## Research loop - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `brief` | `GET` | `/projects/{id}/brief` | The project context packet: hypotheses, runs, decisions, next actions. | -| `hypothesis:add` | `POST` | `/hypotheses:add` | Pose a falsifiable claim as a node. | -| `hypothesis:update` | `POST` | `/hypotheses:update` | Move a hypothesis through its lifecycle. | -| `experiment:plan` | `POST` | `/experiments:plan` | Declare config, metric, and success criterion before a run. | -| `decision:add` | `POST` | `/decisions:add` | Record a decision and what it rests on. | -| `eval:define` | `POST` | `/evals:define` | Define a reusable metric + direction + threshold. | -| `reproduce` | `local` | `/reproduce` | Assemble a reproducibility packet (`--check` fails when incomplete). | - -## Runs & executions - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `run:record` | `local` | `/runs:record` | Record a run as an empirical node; auto-captures git state. | -| `run:compare` | `GET` | `/runs:compare` | Comparison matrix across a project's runs (depth ≤ 3). | -| `leaderboard` | `local` | `/runs:leaderboard` | Rank runs by one metric. | -| `run:spool:list` | `local` | `/runs:spool` | List queued offline runs. | -| `run:spool:flush` | `local` | `/runs:spool/flush` | Replay queued runs. | -| `run:spool:clear` | `local` | `/runs:spool` | Drop queued runs without posting. | -| `exec:start` | `POST` | `/nodes/{id}/executions` | Start a managed execution on a node. | -| `exec:list` | `GET` | `/nodes/{id}/executions` | List managed executions. | -| `exec:stop` | `POST` | `/nodes/{id}/executions/{exec_id}/terminate` | Stop a managed execution. | -| `run:chart` | `local` | `/runs:chart` | Score-progression chart (vega-lite) from a project's runs, attached to the project node. | -| `agent:run` | `local` | `/agent/run` | Run the Atlas agent runtime (Modal sandbox cognition). | - -## Compute - -The cross-provider GPU marketplace. Pass-through pricing (provider cost plus a small fee); bring-your-own-key offers rank as free. See [web views → Compute](/atlas/web-views) for how leases surface in the app. - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `compute:catalog` | `local` | `/compute/options` | Cheapest GPUs across every provider; `--gpu`, `--provider`, `--min-vram`, `--max-price`, `--gpus`, `--best`, `--all`. | -| `compute:up` | `local` | `/compute/leases` | Launch a GPU VM. Zero flags = cheapest available; `--dry-run` previews; `--node` attaches the lease to a node. | -| `compute:list` | `GET` | `/compute/leases` | List running leases (provider, GPU, $/hr, status). | -| `compute:ssh` | `GET` | `/compute/leases/{lease_id}/connection` | SSH command + connection details for a lease. | -| `compute:release` | `POST` | `/compute/leases/{lease_id}/release` | Release a lease and stop billing; managed leases reconcile to actual hours. | - -## Optimize - -GEPA search and refereed campaigns. See [Optimize & autoresearch](/atlas/optimize) for the full flag sets and `atlas help optimize:start --schema --format=json` for the authoritative request shape. - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `optimize:start` | `local` | `/optimize:start` | Run a GEPA search over a target artifact; records each candidate as a node. | -| `optimize:status` | `local` | `/optimize:status` | Report a run's live state: budget used, best score, stop reason. | -| `optimize:stop` | `local` | `/optimize:stop` | Gracefully stop a running optimization. | -| `optimize:verify` | `local` | `/optimize:verify` | Referee a candidate over N seeds (mean/std + one-sided t-test). | -| `autoresearch` | `local` | `/autoresearch` | One-command refereed campaign from a plain-English `--goal`. | -| `optimize:progress` | `POST` | `/optimize:progress` | Merge optimizer run state (budget, best score, stop reason) into a control node. | - -## Journal - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `note:add` | `local` | `/notes` | Add a freeform note as an insight node. | -| `notebook:cell` | `local` | `/notebook/cell` | Capture a notebook cell + output as an empirical node. | -| `log:append` | `local` | `/research/log` | Append a lightweight event to the project research log. | -| `log:search` | `POST` | `/research/log/search` | Search the research log by title/body text. | -| `log:tail` | `GET` | `/research/log` | Read recent research-log entries, newest first. | - -## Projects & nodes - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `project:create` | `local` | `/projects/create` | Find-or-create the project root (dedupe-aware). | -| `project:list` | `local` | `/projects` | List project roots. | -| `project:merge` | `local` | `/projects/merge` | Collapse duplicate project roots. | -| `node:create` | `POST` | `/nodes/commit-new` | Create and save a node in one request. | -| `node:save` | `POST` | `/nodes/{id}/commit` | Save staged changes to a node. | -| `node:show` | `GET` | `/nodes/{id}` | Show one node. | -| `node:list` | `GET` | `/nodes` | List visible nodes. | -| `node:history` | `GET` | `/nodes/{id}/audit` | List a node's history events. | -| `node:branch` | `POST` | `/nodes/{id}/branch` | Branch a node. | -| `node:merge` | `POST` | `/nodes/merge` | Merge nodes into a resolved node. | -| `node:resolve` | `GET` | `/nodes/resolve-by-slug` | Resolve a slug to a node. | -| `node:share` | `local` | `/nodes/share` | Set visibility and print the web URL. | -| `node:delete` / `node:delete-bulk` | `DELETE` / `POST` | `/nodes/{id}`, `/nodes/bulk-delete` | Delete one or many nodes. | -| `program:snapshot` | `GET` | `/nodes/{id}/campaign/snapshot` | Resolve the program root snapshot. | - -## Links, maps, access & labels - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `map:view` | `GET` | `/graph` | Structured map projection. | -| `map:tree` | `GET` | `/nodes/{id}/tree` | Rendered tree. | -| `map:lineage` | `GET` | `/nodes/{id}/ancestry` | Rendered lineage. | -| `map:summary` | `GET` | `/nodes/{id}/summary` | Rendered summary. | -| `link:add` | `POST` | `/nodes/{id}/parents/add` | Add a dependency link. | -| `link:remove` | `POST` | `/nodes/{id}/parents/remove` | Remove a dependency link. | -| `link:children` / `link:parents` | `GET` | `/nodes/{id}/children`, `/parents` | Page children or parents. | -| `access:show` / `access:set` | `GET` / `PUT` | `/nodes/{id}/access-policy` | Read or set a node access policy. | -| `access:set-bulk` / `access:summaries` | `POST` | `/nodes/access-policy/...` | Batch access operations. | -| `draft:create` | `POST` | `/nodes` | Create a staged node shell. | -| `draft:lock` / `draft:renew` / `draft:unlock` | `POST` | `/nodes/{id}/stage/lease/...` | Coordinate multi-agent edits. | -| `draft:derive-hypothesis` | `POST` | `/nodes/{id}/stage/backfill/hypothesis` | Derive a staged hypothesis from draft content. | -| `draft:derive-insights` | `POST` | `/nodes/{id}/stage/backfill/insights` | Derive staged insights from draft content. | -| `label:create` | `POST` | `/nodes/{root_id}/tags` | Create a reusable label. | -| `label:assign` | `PUT` | `/nodes/{id}/tags` | Assign labels to a node. | -| `label:update` / `label:delete` | `PATCH` / `DELETE` | `/nodes/{root_id}/tags/{tag_id}` | Edit or delete a label. | - -## Evidence - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `evidence:add` | `POST` | `/nodes/{id}/artifacts/uploads/prepare` | One-shot upload (prepare → write → finalize). | -| `evidence:list` / `evidence:show` | `GET` | `/nodes/{id}/artifacts[/{artifact_id}]` | List or inspect evidence. | -| `evidence:note` | `PATCH` | `/nodes/{id}/artifacts/{artifact_id}/note` | Edit an evidence note. | -| `evidence:link` / `evidence:refresh` | `POST` | `/nodes/{id}/remote-artifacts/...` | Public HTTPS JSON evidence by URL. | -| `evidence:download` | `GET` | `/blobs` | Download raw bytes by path. | -| `evidence:files` | `GET` | `/users/me/files` | List all evidence you own. | -| `evidence:delete` / `evidence:delete-bulk` | `DELETE` / `POST` | `/nodes/{id}/artifacts/...` | Delete one or many (requires `--yes`). | - -## Code state & integrations - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `repo:capture` | `POST` | `/agent/projects/{id}/repo/capture` | Record code state on a node; `--pin` to tag it. | -| `repo:pin` | `POST` | `/agent/projects/{id}/repo/pin` | Pin a commit as an immutable tag. | -| `repo:push` | `local` | `/agent/runner/repo/push` | Push a branch from inside an Atlas sandbox. | -| `github:link` | `GET` | `/auth/github/install-url` | Browser flow to connect GitHub. | -| `github:set` | `POST` | `/auth/github/pat` | Connect GitHub with a PAT. | -| `github:reconnect` | `GET` | `/auth/github/install-url` | Refresh an expired GitHub token. | -| `github:status` | `GET` | `/auth/github/status` | Show GitHub status. | -| `github:refresh-repos` / `github:disconnect` | `POST` / `DELETE` | `/auth/github/...` | Refresh repos or disconnect. | -| `integration:status` | `GET` | `/auth/integrations/status` | Show all integration status. | -| `integration:huggingface:set` / `:remove` | `PUT` / `DELETE` | `/auth/integrations/huggingface` | Store or remove a Hugging Face access token. | -| `integration:wandb:set` / `:remove` | `PUT` / `DELETE` | `/auth/integrations/wandb` | Store or remove a W&B API key. | - -## Public archive - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `explore` | `GET` | `/explore` | Browse the public Atlas archive of research graphs (authors, stars, forks, papers). | -| `competitions` | `GET` | `/competitions` | List open research competitions with graph-backed leaderboards. | -| `competition` | `GET` | `/competitions/{slug}` | Show a competition and its full leaderboard. | -| `researchers` | `GET` | `/researchers` | Browse public researchers. | - -## Export / import - -| Command | Method | Route | Use | -| --- | --- | --- | --- | -| `map:export` | `POST` | `/export` | Export a subgraph. | -| `map:import` | `POST` | `/import` | Import a subgraph (fork). | -| `history:export` | `GET` | `/legacy/history/export.jsonl` | Export map history as JSONL. | -| `map:summary:export` | `POST` | `/export-summary` | Markdown summary. | -| `map:summary:pdf` / `map:summary:render-pdf` | `POST` | `/export-summary-pdf` | Summary PDF. | -| `map:summary:stream` | `POST` | `/export-summary-stream` | Streamed summary. | - -For source indexing, search, and research-answer commands, use `atlas help library:search`, `atlas help library:ask`, and `atlas help research:ask`. For auth, keys, config, global flags, and output formats, see [CLI overview & conventions](/atlas/cli-overview). diff --git a/src/content/atlas/docs.json b/src/content/atlas/docs.json deleted file mode 100644 index a8b8a0a..0000000 --- a/src/content/atlas/docs.json +++ /dev/null @@ -1,83 +0,0 @@ -{ - "$schema": "https://mintlify.com/docs.json", - "name": "Atlas", - "navigation": { - "tabs": [ - { - "tab": "Guides", - "groups": [ - { - "group": "Start", - "pages": [ - "index", - "installation", - "quickstart", - "graph-model" - ] - }, - { - "group": "Set up", - "pages": [ - "authentication", - "api-keys", - "billing" - ] - }, - { - "group": "The research loop", - "pages": [ - "research-loop", - "runs", - "optimize", - "reproduction" - ] - }, - { - "group": "Work with graphs", - "pages": [ - "evidence", - "forking", - "web-views", - "skills" - ] - }, - { - "group": "Agents", - "pages": [ - "onboard-agent" - ] - } - ] - }, - { - "tab": "Reference", - "groups": [ - { - "group": "CLI and API", - "pages": [ - "cli-overview", - "commands", - "rest-api" - ] - } - ] - } - ], - "global": { - "anchors": [ - { "anchor": "tryatlas.sh", "href": "https://tryatlas.sh" }, - { "anchor": "Open Atlas", "href": "https://app.syntheticsciences.ai/atlas" }, - { "anchor": "llms-full.txt", "href": "https://app.syntheticsciences.ai/documentation/llms-full.txt" }, - { "anchor": "skill.md", "href": "https://app.syntheticsciences.ai/documentation/skill.md" }, - { "anchor": "GitHub", "href": "https://github.com/synthetic-sciences" } - ] - } - }, - "navbar": { - "primary": { - "type": "button", - "label": "Open Atlas", - "href": "https://app.syntheticsciences.ai/atlas" - } - } -} diff --git a/src/content/atlas/evidence.mdx b/src/content/atlas/evidence.mdx deleted file mode 100644 index f4fb794..0000000 --- a/src/content/atlas/evidence.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "Evidence & files" -description: "Attach durable files, metrics, and external JSON to graph nodes." -icon: "file-text" ---- - -Evidence records attach durable files to nodes: run outputs, logs, PDFs, datasets, figures, patches, and notes. Evidence is raw support. Nodes hold the interpretation. Keeping that distinction makes later review easier. - -## Upload - -The one-shot uploader prepares, writes, and finalizes in one call: - -```bash -atlas evidence:add \ - --node nd_... \ - --items '[{"local_path":"./runs/baseline/metrics.json","artifact_type":"json","note":"raw baseline metrics"}]' \ - --format=json -``` - -It accepts up to 50 files and 100 MB per file. Supported `artifact_type` values include `text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`, `checkpoint`, `binary`, and `diff_carousel`. - -## Commands - -| Command | Use | -| --- | --- | -| `evidence:add` | One-shot prepare, upload, and finalize. | -| `evidence:prepare` / `evidence:finalize` | Lower-level upload flow for custom uploaders. | -| `evidence:list` | List evidence attached to one node. | -| `evidence:show` | Inspect one evidence item. | -| `evidence:note` | Add, update, or clear an evidence note. | -| `evidence:download` | Download raw bytes by storage path. | -| `evidence:files` | List every evidence file you own, across nodes. | -| `evidence:link` / `evidence:refresh` | Attach or refresh public HTTPS JSON evidence by URL. | -| `evidence:delete` / `evidence:delete-bulk` | Delete one or many items (requires `--yes`). | - -## Lower-level flow - -Use prepare/finalize only when an external uploader needs the prepared target before finalization: - -```bash -atlas evidence:prepare \ - --node nd_... \ - --items '[{"filename":"baseline.json","artifact_type":"json","media_type":"application/json"}]' - -atlas evidence:finalize --node nd_... --batch-token batch_... -``` - -## Inspect and annotate - -```bash -atlas evidence:list --node nd_... --format=json -atlas evidence:show --node nd_... --artifact-id art_... --format=json -atlas evidence:note --node nd_... --artifact-id art_... --note "baseline metrics + raw stderr" -``` - -## Linked evidence - -Attach a public HTTPS JSON record without uploading a file. Useful for live metrics: - -```bash -atlas evidence:link \ - --node nd_... \ - --remote-artifact-id metrics-live \ - --url https://example.com/results.json \ - --title "external run metrics" \ - --rows-path data.rows \ - --row-id id \ - --format=json -``` - -Refresh it later with `evidence:refresh` using the same arguments. - -## Destructive actions - -```bash -atlas evidence:delete --node nd_... --artifact-id art_... --yes -atlas evidence:delete-bulk --node nd_... --artifact-ids art_1,art_2 --yes -``` - -Use `--yes` only after confirming the target ids. diff --git a/src/content/atlas/forking.mdx b/src/content/atlas/forking.mdx deleted file mode 100644 index e663d86..0000000 --- a/src/content/atlas/forking.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Forking & portability" -description: "Branch nodes, fork subgraphs across workspaces, and export for review or backup." -icon: "git-fork" ---- - -Atlas treats research like GitHub treats code: branch to explore alternatives, fork a subgraph into another workspace, and export for review or backup. Lineage is preserved throughout, so a fork knows where it came from. - -## Branch within a graph - -```bash -atlas node:branch --node nd_root --title "try the alternative loss" -``` - -A branch is a child node that depends on its parent but may diverge. Use branches for competing hypotheses or parallel attempts; the [orbit and timeline views](/atlas/web-views) make the branch structure legible. - -## Fork a subgraph across workspaces - -Forking is **export then import**. Select a subgraph, export it, and import it into another workspace or account. - -```bash -# In the source workspace -atlas map:export --node-ids nd_root --include-descendants true --out subgraph.json - -# In the destination workspace -atlas map:import --payload @subgraph.json --format=json -``` - -| Command | Use | -| --- | --- | -| `map:export` | Export a map subset by node ids (with `--include-descendants`, `--max-nodes`). | -| `map:import` | Import a compatible exported subgraph. | - -This is how you hand a research thread to a collaborator, branch a public graph into your own workspace, or seed a new project from a template. - -## Export for backup and review - -```bash -atlas history:export --out history.jsonl -atlas map:summary:export --node-ids nd_root --out summary.md -atlas map:summary:pdf --node-ids nd_root --out summary.pdf -``` - -| Command | Output | -| --- | --- | -| `history:export` | Map history as JSONL (machine backup). | -| `map:summary:export` | Markdown summary (human review). | -| `map:summary:stream` | Streamed summary for agents that want partial output. | -| `map:summary:pdf` / `map:summary:render-pdf` | PDF for external sharing. | - -Use `--out ` for the JSONL, PDF, and streaming outputs. - -## Import safety - -Treat imports as graph mutations. In automation, inspect the payload first and keep the export file as evidence on the controlling node so the fork is auditable: - -```bash -atlas evidence:add --node nd_control \ - --items '[{"local_path":"subgraph.json","artifact_type":"json","note":"imported subgraph source"}]' -``` diff --git a/src/content/atlas/graph-model.mdx b/src/content/atlas/graph-model.mdx deleted file mode 100644 index c365579..0000000 --- a/src/content/atlas/graph-model.mdx +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: "Nodes & links" -description: "Node kinds, the staged/committed lifecycle, links, access, labels, and drafts." -icon: "git-branch" ---- - -Atlas Graphs stores research state as committed nodes connected by links. Each node answers one question: what changed in the research state? If you are new, run the [research loop quickstart](/atlas/quickstart) first. - -## Node kinds - -A node's **kind** is its first-class type. The research-loop verbs create typed nodes for you; `node:create` makes an untyped one. - -| Kind | Created by | Holds | -| --- | --- | --- | -| `hypothesis` | `hypothesis:add` | A falsifiable claim with assumptions and disconfirmers. | -| `empirical` | `run:record`, `notebook:cell` | A recorded run: config, metrics, outcome, code state. | -| `decision` | `decision:add` | A choice and the runs/evidence it rests on. | -| `insight` | `note:add` | A freeform observation worth keeping. | -| `untyped` | `node:create`, `draft:create` | Anything that does not fit a typed kind yet. | - -`experiment:plan` nodes (the plans recorded runs execute) and project roots round out the structure. See [the research loop](/atlas/research-loop) for the typed-node workflow. - -## The staged / committed lifecycle - -Nodes move from **staged** to **committed**: - -- A **draft** is a staged shell. Create one with `draft:create`, edit it, then commit with `node:save`. -- `node:create` does both at once: create and save a durable node in one request. -- A **save** is a recorded state change with revision history you can audit. - -```bash -atlas node:create \ - --payload-json '{ - "local_temp_node_id": "tmp-baseline-question", - "parent_ids": [], - "staged_payload": { - "title": "evaluate the sparse-attention baseline", - "content": "Which baseline should we trust before ablations?", - "summary": "Root question for baseline selection.", - "kind": "untyped" - } - }' \ - --format=json -``` - -Inspect the exact envelope with `atlas help node:create --schema --format=json` before building payloads. - -## Node lifecycle commands - -| Command | Use | -| --- | --- | -| `draft:create` | Create an uncommitted node shell. | -| `node:create` | Create and save a new node. | -| `node:save` | Save staged changes to an existing node. | -| `node:show` | Inspect one node. | -| `node:list` | List visible nodes. | -| `node:history` | List a node's history events. | -| `node:files` | List evidence files for one node. | -| `node:delete` / `node:delete-bulk` | Delete one or many nodes (requires `--yes`). | - -## Links and topology - -Links record dependency from prior context to derived work. Branching and merging are graph operations. - -```bash -atlas node:branch --node nd_root --title "run the reference baseline" -atlas link:add --node nd_child --parent-id nd_root -atlas map:tree --node nd_root --max-depth 4 -``` - -| Command | Use | -| --- | --- | -| `map:view` | Read a structured map projection with depth, paging, filters. | -| `node:branch` | Create a child branch from a node. | -| `node:merge` | Merge nodes into a resolved node. | -| `link:add` / `link:remove` | Add or remove a dependency link. | -| `link:parents` / `link:children` | Page direct parents or children. | -| `node:resolve` | Resolve a slug to a node. | -| `program:snapshot` | Resolve the program root snapshot for a node. | - -Merge only when there is a resolved synthesis. Do not merge unresolved alternatives just to shorten the tree. - -## Rendered views - -```bash -atlas map:lineage --node nd_root --max-depth 4 --format=json -atlas map:summary --node nd_root --max-nodes 50 --format=json -atlas map:tree --node nd_root --max-depth 5 -``` - -Use rendered views for terminal agents. Use `map:view` when you need the raw projection for your own UI. The web app renders the same graph as cards, orbit, and timeline. See [Web app views](/atlas/web-views). - -## Access - -```bash -atlas access:show --node nd_root --format=json -atlas node:share --node nd_root --visibility public -``` - -`node:share` sets visibility (`private`, `unlisted`, `public`) and prints the canonical web URL. For batches, use `access:set-bulk` and `access:summaries`. - -## Labels - -```bash -atlas label:create --root-node-id nd_root --name validated -atlas label:assign --node nd_child --tag-ids tag_... -``` - -| Command | Use | -| --- | --- | -| `label:create` | Create a reusable, root-scoped label. | -| `label:assign` | Assign labels to a node. | -| `label:update` / `label:delete` | Edit or remove a label. | - -Use labels for workflow state such as `planned`, `running`, `validated`, or `blocked`. - -## Concurrency - -When multiple agents may edit the same node, use draft locks: - -```bash -atlas draft:lock --node nd_... -atlas draft:renew --node nd_... --stage-session-id session_... -atlas draft:unlock --node nd_... --stage-session-id session_... -``` - -A long-running agent should lock the draft, renew while editing, and unlock when the staged work is committed or abandoned. - -## Linked evidence - -Attach a public HTTPS JSON record to a node by URL without uploading a file: - -```bash -atlas evidence:link \ - --node nd_... \ - --remote-artifact-id metrics-live \ - --url https://example.com/results.json \ - --title "external run metrics" \ - --format=json -``` - -See [Evidence & files](/atlas/evidence) for uploads and notes. diff --git a/src/content/atlas/index.mdx b/src/content/atlas/index.mdx deleted file mode 100644 index e23c258..0000000 --- a/src/content/atlas/index.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: "Atlas" -description: "The research graph: hypotheses, experiment plans, recorded runs, evidence, and decisions in one durable, shared structure." -icon: "git-branch" ---- - -Atlas stores an investigation as durable nodes connected by links. A graph can hold the root question, hypotheses, experiment plans, recorded runs, code state, evidence, and decisions. This gives researchers and agents the same history when work moves between sessions. - -Delegated research scatters across chats, notebooks, logs, and memory. Atlas gives it a shared map, so humans and agents return to the same state, audit what happened, and decide what to do next. Agents read that state back as a context packet with `atlas brief`. - - - - `npm i -g @synsci/atlas@latest`, sign in, and verify with `atlas doctor`. 159 commands, nine bundled skills. - - - Project, hypothesis, plan, recorded run, comparison, decision, brief. The full loop in one sitting. - - - Node kinds, the staged/committed lifecycle, links, access, labels, and drafts. - - - One paste that installs Atlas, logs in, and loads the bundled skills. - - - -## What lives in a graph - -| Object | Created by | What it captures | -| --- | --- | --- | -| Project | `project:create` | The root node for a folder or repo. | -| Hypothesis | `hypothesis:add` | A falsifiable claim, its assumptions, and its disconfirmers. | -| Experiment plan | `experiment:plan` | The config, metric, and success criterion, declared before the run. | -| Run | `run:record` | Config, metrics, outcome, and auto-captured code state. | -| Decision | `decision:add` | A choice and the runs or evidence it rests on. | -| Insight / note | `note:add` | A freeform observation worth keeping. | -| Evidence | `evidence:add` | Raw files, metrics, logs, or external JSON on a node. | - -An **indexed source** is a repository, documentation site, paper, dataset, or local folder that a graph can search and cite. A **project** is the root node for one folder or repository. Use the `library:*` command namespace to add and search sources. Discover the exact commands through the [CLI overview](/atlas/cli-overview). - -## The lifecycle - -Nodes move from **staged** to **committed**. A draft is a staged shell you can edit; a save commits it into the durable graph with revision history. Most workflows commit directly with `node:create` or the research-loop verbs; reach for `draft:*` only when several agents coordinate edits on one node. - -Links record dependency and lineage, so `map:lineage` can answer "why did we do this?" long after the fact. Branching and merging are graph operations, not folders. - -Every recorded run carries an **outcome** (`success`, `failure`, or `inconclusive`) and, when it failed, a **failure mode** (`diverged`, `oom`, `data_bug`, `code_bug`, `underperformed`, `other`). Failures are first-class: recording them is how the next agent avoids repeating them. - -## Minimum working setup - -One CLI, `@synsci/atlas`, drives everything. It is a direct HTTP client for the Atlas API at `https://app.syntheticsciences.ai/api/v1`; there is no separate transport to configure, and no Atlas MCP server. - -```bash -npm i -g @synsci/atlas@latest -atlas login -atlas doctor --format=json -``` - -`atlas login` opens a browser approval flow and stores an API key locally. `atlas doctor` confirms auth, backend reachability, and the nine bundled skills. From there, run the [research loop](/atlas/research-loop), or index sources with `atlas library:add`. - -## Built for agents - -The CLI bundles nine skills that teach coding agents how to use Atlas. `atlas install` places them into supported agent directories on your machine. The published machine-readable references are: - -- [llms.txt](https://app.syntheticsciences.ai/documentation/llms.txt): documentation map. -- [llms-full.txt](https://app.syntheticsciences.ai/documentation/llms-full.txt): full command surface. -- [skill.md](https://app.syntheticsciences.ai/documentation/skill.md): bundled Atlas skill. - -See [Onboard a coding agent](/atlas/onboard-agent) for a one-paste setup prompt. - -## Where to go next - -- New here? Start with the [research loop quickstart](/atlas/quickstart). -- Need the model? Read [Nodes & links](/atlas/graph-model). -- Reproducing a result? See [Reproduction & code state](/atlas/reproduction). -- Looking for a command? See the [CLI & API reference](/atlas/commands). -- Want the agent that drives all of this? Meet [OpenScience](/openscience/index). -- Product site: [tryatlas.sh](https://tryatlas.sh). diff --git a/src/content/atlas/installation.mdx b/src/content/atlas/installation.mdx deleted file mode 100644 index 56718da..0000000 --- a/src/content/atlas/installation.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "Installation" -description: "Install the Atlas CLI, sign in, and verify the runtime." -icon: "package-check" ---- - -One package drives the whole Atlas suite: `@synsci/atlas`. It needs Node `18+` and an Atlas account. - - -Always install `@latest`. Versions below the current release are deprecated on npm; never pin an old patch version in scripts or docs. - - - - - ```bash - npm i -g @synsci/atlas@latest - atlas --version - ``` - - The package exposes 159 commands and bundles nine skills. It works on macOS, Linux, and Windows. - - - - ```bash - atlas login - ``` - - The CLI opens a browser approval flow, redeems a one-time token, and stores an Atlas API key in your local profile. On a headless box, create a `thk_*` key in the app and export it as `ATLAS_API_KEY` instead. See [Authentication](/atlas/authentication). - - - - ```bash - atlas doctor --format=json - atlas whoami --format=json - atlas help --format=json - ``` - - `doctor` checks config, auth, backend reachability, and that the nine bundled skills are present. - - - - ```bash - atlas install - ``` - - `install` detects coding agents on the machine (Claude Code, Cursor, Codex, Windsurf, Aider, Continue, Goose) and drops the bundled Atlas skills into each. Use `--dry-run` to preview, `--agent=` for non-interactive installs, and `--uninstall` to reverse. - - - -## What success looks like - -`atlas doctor --format=json` reports a reachable backend, an authenticated profile, and nine skills. `atlas whoami --format=json` returns the signed-in account. If login succeeds but commands fail, run `doctor` before changing config; it is the fastest way to separate a local problem from an API one. - -## Upgrade - -```bash -npm i -g @synsci/atlas@latest -``` - -Re-running the install is the upgrade. Because old versions are deprecated, staying current is the supported path; there is nothing to pin. - -## Requirements - -| Requirement | Detail | -| --- | --- | -| Node | `18+` | -| Account | An Atlas account at [app.syntheticsciences.ai](https://app.syntheticsciences.ai/atlas) | -| Network | Outbound HTTPS to `https://app.syntheticsciences.ai/api/v1` | - -## Next steps - -- [Authentication](/atlas/authentication) for browser login, API keys, and local config. -- [CLI overview & conventions](/atlas/cli-overview) for the command grammar before you script anything. -- [Research loop quickstart](/atlas/quickstart) to run the loop end to end. -- [CLI overview & conventions](/atlas/cli-overview) to discover source indexing, search, and research commands. diff --git a/src/content/atlas/onboard-agent.mdx b/src/content/atlas/onboard-agent.mdx deleted file mode 100644 index 1f1bb2f..0000000 --- a/src/content/atlas/onboard-agent.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Onboard a coding agent" -description: "One paste that installs Atlas, signs in, loads the skills, and opens the lab." -icon: "bot" ---- - -Atlas is built for agents. Paste the prompt below into Claude Code, Cursor, Codex, or any coding agent and it will install the CLI, sign in, verify the bundled skills, and bootstrap a project. It mirrors the onboarding prompt on the Atlas page in the app. - -## The prompt - -```text -You are setting up Atlas, the research map where my experiments, hypotheses, evidence, and decisions live permanently. Work recorded here survives this chat. A later agent can inherit every run and decision. - -Set it up: -1. Run `npm i -g @synsci/atlas@latest`, then `atlas login`. Ask me to approve the browser prompt. -2. Run `atlas doctor --format=json` to verify auth, the backend, and the 9 bundled skills (atlas, atlas-lab, atlas-frontier, atlas-map, atlas-optimize, atlas-autoresearch, atlas-reproduce, atlas-search, atlas-paper). Run `atlas install` to wire them into this agent. -3. Run `atlas project:create` to bootstrap the project for this folder. It is dedupe-safe and can be run again. -4. Run `atlas brief --project ` and summarize the open hypotheses, recent runs, failures, decisions, and suggested next action. - -House rules: the skills are bundled in the CLI, so do not configure separate skill downloads. Commit code before recording runs because each run captures code state. Never print my full API key. Report only the key prefix, CLI version, doctor result, and account, then tell me the setup is ready. -``` - -## Why it works - -- It installs `@latest` (old versions are deprecated) and uses the browser login, so the agent never fabricates credentials. -- `atlas doctor` is the load-bearing check: it confirms auth and that all nine skills are present before any real work. -- `atlas project:create` is dedupe-aware and safe to re-run every session, so the agent always lands in the right project. -- `atlas brief` returns the context packet, so the agent picks up exactly where the last session stopped. - -## Machine-readable references - -Point the agent at the published surface so it never guesses a flag: - -| Resource | Use | -| --- | --- | -| [llms.txt](https://app.syntheticsciences.ai/documentation/llms.txt) | The map of the docs. | -| [llms-full.txt](https://app.syntheticsciences.ai/documentation/llms-full.txt) | The full command surface (159 commands) and the research loop. | -| [skill.md](https://app.syntheticsciences.ai/documentation/skill.md) | The bundled Atlas skill, ready to drop into an agent. | - -In-session, the agent can introspect any command: - -```bash -atlas help --format=json -atlas help run:record --schema --format=json -``` - -## A scoped variant - -For an agent that only needs to verify an existing install: - -```text -Verify Atlas on this machine. Run `atlas --version`, `atlas doctor --format=json`, -and `atlas whoami --format=json`. Report the version, the doctor result, the -skill count, the authenticated account, and the API key prefix only. Do not -repair anything or print the full key. -``` diff --git a/src/content/atlas/optimize.mdx b/src/content/atlas/optimize.mdx deleted file mode 100644 index d9d1c5e..0000000 --- a/src/content/atlas/optimize.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: "Optimize & autoresearch" -description: "Improve a measurable artifact with the GEPA loop, referee the result, or run the whole refereed campaign from one goal." -icon: "trending-up" ---- - -Once you have a benchmark, Atlas can search for a better artifact such as a prompt, config, or code file. It records each candidate, its lineage, the live budget, and the refereed before-to-after result as graph state. Use the `optimize:*` primitives for direct control or `autoresearch` for a full campaign from one goal. - - -Both surfaces use the [`atlas-optimize`](/atlas/skills) and `atlas-autoresearch` skills. They require `uv` and a reflection-model key for the GEPA reflection step. The workflow uses the existing research-loop primitives rather than a separate engine. - - -## The GEPA loop - -`optimize:start` runs a GEPA search: it mutates the target artifact, scores each candidate against your benchmark, and records the winner. Each candidate becomes an `empirical` node, failures become `failure` nodes, and a control node carries the run state. - -```bash -atlas optimize:start \ - --target ./prompts/system.txt \ - --benchmark ./.atlas/benchmark.sh \ - --objective "raise exact-match on the eval set" \ - --metric max \ - --max-metric-calls 50 \ - --max-seconds 28800 -``` - -| Flag | Purpose | -| --- | --- | -| `--target` | The artifact to optimize (required). | -| `--benchmark` | Command that runs the eval and emits the contract JSON (required). | -| `--objective` | Plain-English goal for the reflection step (required). | -| `--metric` | `max` or `min`, depending on which direction is better. | -| `--max-metric-calls` | Budget in benchmark evaluations. | -| `--max-seconds` | Wall-clock budget mapped to GEPA's timeout. `0` means no limit. When combined with `--max-metric-calls`, the first limit reached stops the run. | -| `--parallel` | Run `K` candidates concurrently, each in its own git worktree. | -| `--stall` | Stop after this many rounds with no improvement. | -| `--gate` | A Goodhart guard (for example a files-unchanged check) that disqualifies cheating candidates. | -| `--ground` | Ground the reflection in indexed library sources. | -| `--resume ` | Continue a prior run, seeding from its best candidate. | - -The harness writes `optimize-result.json` into the run directory and returns the same data from `optimize:start`. It includes the control node id, winner node id, recorded candidate count, and `stop_reason`, so wrappers do not need to scrape stdout. `stop_reason` is one of `budget_exhausted`, `no_improvement`, `objective_met`, `user_cancelled`, or `runtime_error`. - -Track and control a run from its control node: - -```bash -atlas optimize:status --node --format=json # status, budget used, best score, stop reason -atlas optimize:stop --node # graceful stop at the next iteration boundary -``` - -## Referee the result - -A higher score on one seed is not a result. `optimize:verify` is the referee: it replays the candidate at its exact commit across N seeds, computes mean and standard deviation, runs a one-sided t-test against a threshold, and writes a referee-report node. - -```bash -atlas optimize:verify \ - --node \ - --benchmark ./.atlas/benchmark.sh \ - --seeds 10 \ - --threshold 0.72 \ - --metric max -``` - -`--seeds` defaults to `10` and `--alpha` (the significance level) defaults to `0.01`. Verify both the winner and the baseline so the delta is honest. - -## One-command campaigns: autoresearch - -`atlas autoresearch` runs the entire refereed campaign from one sentence. Point it at a forked repo with a `--goal` and it auto-detects the artifact, generates an editable benchmark, measures the seed baseline, **pre-registers a hypothesis and experiment plan before the first candidate** (the plan's timestamp is the guarantee), runs the GEPA search, then referees both the baseline and the winner over N seeds. - -```bash -atlas autoresearch --goal "reduce validation loss on the cifar10 baseline" -``` - -It prints a verified delta: - -```text -VERIFIED: 0.748 → 0.718 (Δ -0.030, p<0.05, n=10) -``` - -| Flag | Purpose | -| --- | --- | -| `--goal` | The plain-English objective (the only required input). | -| `--path` | The repo/fork to operate on (also accepted as a bare positional). | -| `--metric` | `max` or `min`; inferred from the goal verb (reduce/lower → `min`, raise/beat → `max`) when omitted. | -| `--budget` | A wall-clock cap such as `8h`, `90m`, or `2d`. | -| `--max-metric-calls` | Evaluation budget (default `50`). | -| `--seeds` | Referee replications (default `10`); `--alpha` defaults to `0.05`. | -| `--scaffold-only` | Stop after generating the benchmark for review. | -| `--dry-run` | Preview the full plan without spending budget. | -| `--resume` | Continue an interrupted campaign. | -| `--project ` | Attach the campaign under an existing node, including a paper reproduced with `atlas-reproduce`. | -| `--target` / `--benchmark` | Override artifact and benchmark auto-detection. | - -The campaign root's canonical URL (`/nodes/`) is printed at launch so you can watch it in the web views. - -When `--benchmark` is omitted, autoresearch generates an editable scaffold in `.atlas/`: `benchmark.sh` (how to run the eval), `score.py` (one editable `METRIC=` line), and `gate.sh` (a files-unchanged Goodhart guard). Review or edit those before committing real budget. If a repo can't be auto-benchmarked, it stops with a one-line fix rather than guessing. - -## Discover the exact flags - -The flag sets above are the headline options; the registry is the source of truth: - -```bash -atlas help optimize:start --schema --format=json -atlas help autoresearch --schema --format=json -``` - -Recorded candidates, lineage, and referee reports all show up in the [web views](/atlas/web-views) and feed back into the [research loop](/atlas/research-loop). diff --git a/src/content/atlas/quickstart.mdx b/src/content/atlas/quickstart.mdx deleted file mode 100644 index 79bbcfe..0000000 --- a/src/content/atlas/quickstart.mdx +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: "Research loop quickstart" -description: "Run one full cycle: project, hypothesis, plan, recorded run, comparison, decision, brief." -icon: "rocket" ---- - -This is the headline workflow of Atlas Graphs. In one sitting you pose a hypothesis, declare what would change your mind, record a run with its exact code state, rank the results, and log the decision. The next agent (or you, next week) inherits all of it through `atlas brief`. - -Assumes the CLI is installed and you are signed in. If not, see [Installation](/atlas/installation). - - - - ```bash - atlas project:create - ``` - - Run this from your repo. It is dedupe-aware: it finds the existing project for this folder/repo or creates one, so it is safe to re-run every session. Save the returned project id (a slug like `able-helm-1359`). - - - - ```bash - atlas hypothesis:add \ - --project able-helm-1359 \ - --claim "Cosine LR schedule beats step decay on val loss for this model" \ - --rationale "Smoother decay tends to help small-batch runs" \ - --expected-observations "lower metrics.val_loss at the same step budget" \ - --disconfirmers "no gap, or step decay wins" - ``` - - State the falsifiable claim and what would kill it before you test it. Save the hypothesis id. - - - - ```bash - atlas experiment:plan \ - --project able-helm-1359 \ - --hypothesis \ - --metric metrics.val_loss \ - --success-criterion "metrics.val_loss < 2.0" \ - --config '{"schedule":"cosine","lr":3e-4}' - ``` - - Declare the metric and the **success criterion** runs are judged against. The plan pre-allocates a `run_cluster_key` that recorded runs inherit, so repeats fold into one comparable axis. Save the plan id. - - - - ```bash - git add -A && git commit -m "cosine schedule sweep" - - atlas run:record \ - --project able-helm-1359 \ - --plan \ - --config-json '{"schedule":"cosine","lr":3e-4,"seed":17}' \ - --metrics-json '{"val_loss":1.88}' \ - --outcome success - ``` - - `run:record` auto-captures the working tree's git state (repo URL, branch, head commit SHA, and a dirty flag), so commit first. Because the run is bound to the plan with `--plan`, Atlas evaluates the success criterion and stores `criterion_met`. Offline? The run spools to `~/.atlas/spool/` and flushes on the next call. - - - - ```bash - atlas leaderboard --project able-helm-1359 --metric metrics.val_loss - atlas run:compare --project able-helm-1359 \ - --columns title,config.lr,metrics.val_loss,criterion_met --format=table - ``` - - `leaderboard` ranks runs in the metric's better direction with the winner marked. `run:compare` is the full matrix; dot-paths into the captured data (`config.lr`, `metrics.val_loss`) become columns. - - - - ```bash - atlas decision:add \ - --project able-helm-1359 \ - --decision "Adopt cosine schedule for the baseline" \ - --basis , \ - --confidence high - ``` - - Link the runs the decision rests on so `map:lineage` can explain it later. - - - - ```bash - atlas hypothesis:update --node --status supported --because - atlas brief --project able-helm-1359 - ``` - - Move the hypothesis through its lifecycle, then reload `brief`. Its `suggested_next` drives the next cycle. - - - -## What you just built - -A project with a hypothesis, an experiment plan, a recorded run carrying its exact code state, a ranked comparison, and a decision linked to its basis. Every piece is durable and navigable in the [web app views](/atlas/web-views). - -## The loop, condensed - -```text -project:create → brief → hypothesis:add → experiment:plan - → (commit) → run:record --plan → run:compare / leaderboard - → decision:add → hypothesis:update → brief (suggested_next) -``` - -## Next steps - -- [The research loop](/atlas/research-loop) for the full workflow reference, including `eval:define`. -- [Runs & flight recorder](/atlas/runs) for everything `run:record` and `run:compare` capture. -- [Reproduction & code state](/atlas/reproduction) to package a result for exact replay. diff --git a/src/content/atlas/reproduction.mdx b/src/content/atlas/reproduction.mdx deleted file mode 100644 index af15d6a..0000000 --- a/src/content/atlas/reproduction.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Reproduction & code state" -description: "Package a result for exact replay: config, captured code, dataset, and success criterion." -icon: "repeat-2" ---- - -A result is only as good as your ability to reproduce it. Atlas captures the code state behind every recorded run, and `reproduce` assembles the whole packet on demand. Pin the commits that matter so they stay reachable forever. - -## Turn a paper into a graph - -The `atlas-reproduce` skill runs the other direction: start from someone else's paper and end with a reproduced result in your graph. Hand your agent an arXiv id (or a paper URL or repo) and it: - -1. Indexes the paper with `atlas library:add --type research_paper --url https://arxiv.org/abs/`. -2. Finds the code behind it. -3. Runs a **minimal reproduction** of the headline claim. -4. Lays the result out as a graph: paper → claim → setup → result. - -When the paper omits a hyperparameter, dataset split, hardware detail, or other required input, the agent asks for it and records the answer as a `decision` node. This keeps the assumptions visible. Continue from the reproduced node with `atlas autoresearch --project `, or use `atlas fork` to carry the code state into another graph. - -## Reproducibility packet - -```bash -atlas reproduce --node --format=json -atlas reproduce --node --check -``` - -`reproduce` resolves the exact **config**, **captured code state** (repo, branch, commit, pin), **dataset ref**, and **success criterion** for a run or result node. Add `--check` to fail with the missing pieces when the packet is incomplete, including a dirty working tree at record time. Use `--check` in CI to reject results that cannot be replayed. - -## Capture code state - -`run:record` captures code state automatically (see [Runs](/atlas/runs)). To attach or refresh it on any node, or to pin a milestone: - -```bash -atlas repo:capture --node \ - --repo-url "$(git remote get-url origin)" \ - --branch-name "$(git rev-parse --abbrev-ref HEAD)" \ - --head-commit-sha "$(git rev-parse HEAD)" \ - --pin true -``` - -`repo:capture` records the repo/branch/commit behind a node so a public-graph viewer can open the exact code. `--pin true` also creates an immutable tag (default `atlas/-r`) so the commit stays reachable even if the branch moves. - -| Command | Use | -| --- | --- | -| `repo:capture` | Record code state on a node; `--pin` to tag it immutably. | -| `repo:pin` | Pin an existing commit as an immutable tag (capture-by-value). | -| `repo:push` | From inside an Atlas sandbox, bundle the current branch and push it via the backend (no token in the sandbox). | - -## Connect GitHub first - -Capturing and pinning need a connected GitHub account: - -```bash -atlas github:link # browser flow (recommended) -atlas github:set --token-env GITHUB_PAT # CLI-only with a PAT -atlas github:status --format=json -atlas github:reconnect # refresh an expired token -``` - -`atlas doctor` warns when a GitHub token has expired; `github:reconnect` is the follow-up. - -## Recommended practice - -- **Commit before you record.** A clean tree is what makes `reproduce --check` pass. -- **Pin milestones.** `repo:capture --pin true` on the runs behind a decision keeps the exact code reachable. -- **Gate on reproducibility.** Run `atlas reproduce --node --check` in CI before promoting a result. diff --git a/src/content/atlas/research-loop.mdx b/src/content/atlas/research-loop.mdx deleted file mode 100644 index 501a793..0000000 --- a/src/content/atlas/research-loop.mdx +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: "The research loop" -description: "Brief, hypotheses, experiment plans, decisions, and evals as a durable workflow." -icon: "workflow" ---- - -The research loop turns an investigation into durable, comparable graph state. Every step leaves a node a later agent can read back, so research survives the session it happened in. For a hands-on walkthrough, do the [quickstart](/atlas/quickstart) first; this page is the workflow reference. - -```text -brief → hypothesis:add → experiment:plan → run:record → run:compare / leaderboard - → decision:add → hypothesis:update → brief (suggested_next drives the next cycle) -``` - -## Start every session with brief - -```bash -atlas brief --project able-helm-1359 -atlas brief --project able-helm-1359 --full -``` - -`brief` is the project context packet for agents. It contains open hypotheses, recent runs, failure clusters, decisions, open branches, and runnable `suggested_next` actions. Read it before acting. `--full` raises the per-section limits for a deeper packet. - -## Pose a hypothesis - -```bash -atlas hypothesis:add \ - --project able-helm-1359 \ - --claim "Cosine LR beats step decay on val loss" \ - --assumptions "same data, same step budget" \ - --expected-observations "lower metrics.val_loss" \ - --disconfirmers "no gap, or step decay wins" \ - --rationale "smoother decay helps small-batch runs" -``` - -A hypothesis is a first-class node: the falsifiable claim, why you believe it, what would confirm it, and what would kill it. - -| Flag | Meaning | -| --- | --- | -| `--claim` | The falsifiable claim, one sentence (required). | -| `--rationale` | Why you believe it might be true. | -| `--expected-observations` | Comma-separated observations that would support it. | -| `--disconfirmers` | Comma-separated observations that would kill it. | -| `--assumptions` | Comma-separated assumptions the claim rests on. | -| `--status` | `proposed` (default), `testing`, `supported`, `weakened`, `rejected`. | - -## Plan the experiment - -```bash -atlas experiment:plan \ - --project able-helm-1359 \ - --hypothesis \ - --metric metrics.val_loss \ - --success-criterion "metrics.val_loss < 2.0" \ - --config '{"schedule":"cosine"}' \ - --risks "could overfit at high lr" -``` - -Declare what the experiment tests **before** running it: the hypothesis, the config, the metric, and the success criterion runs are judged against. The plan pre-allocates a `run_cluster_key` that `run:record --plan` inherits, so repeats fold into one comparable cluster. - -## Record and compare - -Recording runs and comparing them is the flight recorder. See [Runs & flight recorder](/atlas/runs) for the full surface. - -```bash -atlas run:record --project able-helm-1359 --plan \ - --config-json '{"schedule":"cosine","lr":3e-4}' \ - --metrics-json '{"val_loss":1.88}' --outcome success -atlas leaderboard --project able-helm-1359 --metric metrics.val_loss -``` - -Binding a run to its plan with `--plan` makes Atlas evaluate the success criterion and store `criterion_met`. - -## Define reusable evals - -```bash -atlas eval:define \ - --project able-helm-1359 \ - --name cifar10-val \ - --metric metrics.val_loss \ - --direction min \ - --threshold 2.0 -``` - -An eval names a metric, its better direction, and an optional threshold, so plans and leaderboards share one definition of "good". - -| Flag | Meaning | -| --- | --- | -| `--name` | Eval name (e.g. `cifar10-val`). | -| `--metric` | Metric dot-path runs report. | -| `--direction` | `min` (lower is better) or `max`. | -| `--threshold` | Optional pass threshold. | -| `--dataset-ref` | Optional dataset URL, path, or library source id. | - -## Record the decision - -```bash -atlas decision:add \ - --project able-helm-1359 \ - --decision "Adopt cosine schedule for the baseline" \ - --basis , \ - --alternatives "step decay, linear warmup" \ - --confidence high -``` - -Link the runs, evidence, and hypotheses a decision rests on so `map:lineage` answers "why did we do this?" later. - -| Flag | Meaning | -| --- | --- | -| `--decision` | The decision, one sentence (required). | -| `--basis` | Node ids/slugs the decision rests on. | -| `--alternatives` | Comma-separated alternatives considered. | -| `--confidence` | `low`, `medium` (default), `high`. | -| `--reversible` | Whether it can be cheaply reversed (default true). | - -## Close the loop - -```bash -atlas hypothesis:update --node --status supported --because --note "cosine won by 0.12" -atlas brief --project able-helm-1359 -``` - -`hypothesis:update` moves a hypothesis through `proposed → testing → supported | weakened | rejected`, citing the runs or evidence that justify the change. Then reload `brief` and let `suggested_next` drive the next cycle. - -## Journal entries - -Not everything is an experiment. Capture observations and notebook cells without a full run: - -```bash -atlas note:add --project able-helm-1359 --text @notes.md -atlas notebook:cell --project able-helm-1359 --config-json '{...}' --metrics-json '{...}' -``` - -`note:add` records an insight node; `notebook:cell` captures a cell and its output as an empirical node with the same spool semantics as `run:record`. diff --git a/src/content/atlas/rest-api.mdx b/src/content/atlas/rest-api.mdx deleted file mode 100644 index 89ded4c..0000000 --- a/src/content/atlas/rest-api.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "REST API" -description: "The direct HTTP API behind the Atlas CLI: base URL, auth, and route families." -icon: "book-open" ---- - -The Atlas CLI is a thin client over a direct HTTP API. Anything the CLI does, you can do with a bearer token and `curl`. For day-to-day work prefer the CLI; it handles login, retries, idempotency keys, uploads, and output formatting. - -## Base URL - -```text -https://app.syntheticsciences.ai/api/v1 -``` - -## Authentication - -Send an Atlas API key as a bearer token: - -```bash -curl -H "Authorization: Bearer $ATLAS_API_KEY" \ - https://app.syntheticsciences.ai/api/v1/auth/status -``` - -Keys are prefixed `thk_` and minted with `atlas key:create` or in the app. See [API keys](/atlas/api-keys). - - -Atlas uses direct REST and the CLI. There is no Atlas MCP server. Retired MCP-era authentication and device-pairing endpoints return `HTTP 426 Upgrade Required`. Use `atlas login` or a `thk_*` key instead. - - -## Route families - -| Family | Representative routes | CLI reference | -| --- | --- | --- | -| Auth & account | `GET /auth/status`, `POST /auth/cli/browser/start`, `GET\|POST\|DELETE /auth/api-keys`, `PATCH /users/me` | [Authentication](/atlas/authentication) | -| Graph & nodes | `GET /graph`, `POST /nodes/commit-new`, `GET /nodes/{id}/tree`, `POST /nodes/{id}/branch` | [Graph commands](/atlas/commands) | -| Research loop | `GET /projects/{id}/brief`, `POST /hypotheses:add`, `POST /experiments:plan`, `POST /decisions:add` | [The research loop](/atlas/research-loop) | -| Runs | `LOCAL /runs:record`, `GET /runs:compare`, `LOCAL /runs:leaderboard` | [Runs & flight recorder](/atlas/runs) | -| Evidence | `GET\|POST /nodes/{id}/artifacts`, `POST /nodes/{id}/artifacts/uploads/prepare` | [Evidence & files](/atlas/evidence) | -| Indexed sources | `GET\|POST /sources`, `POST /search`, `POST /documents/ask`, `POST /documents/jobs` | [CLI overview](/atlas/cli-overview) | -| Research | `POST /research/oracle`, `POST /research/jobs`, `GET /usage/summary` | [CLI overview](/atlas/cli-overview) | -| Export / import | `POST /export`, `POST /import`, `GET /legacy/history/export.jsonl` | [Forking & portability](/atlas/forking) | -| Integrations | `GET /auth/github/status`, `POST /auth/github/pat`, `PUT /auth/integrations/wandb` | [Authentication](/atlas/authentication) | - -## Output and idempotency - -- Append `--format=json` on the CLI for lossless output; the API always returns JSON. -- Pass `--idempotency-key` (CLI) or an `Idempotency-Key` header (HTTP) when retrying writes from an orchestrator. -- Destructive writes require `--yes` on the CLI; over HTTP they are ordinary `DELETE`/terminate routes, so gate them in your own tooling. - -## Discover the exact shape - -The command registry is the source of truth for routes, required fields, and schemas: - -```bash -atlas help --format=json # every command with its endpoint -atlas help run:record --schema --format=json # the full request body shape -``` diff --git a/src/content/atlas/runs.mdx b/src/content/atlas/runs.mdx deleted file mode 100644 index 7f658b1..0000000 --- a/src/content/atlas/runs.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "Runs & flight recorder" -description: "Record runs with auto-captured code state, then compare and rank them." -icon: "flask-conical" ---- - -The flight recorder posts a single experiment run as an empirical node under a project: config, metrics, stdout tail, and outcome. It captures the exact code state automatically, so a result always points back at the commit that produced it. - -## Record a run - -```bash -git add -A && git commit -m "lr sweep" - -atlas run:record \ - --project able-helm-1359 \ - --plan \ - --title "lr=3e-4 seed=17" \ - --config-json '{"lr":3e-4,"seed":17}' \ - --metrics-json '{"val_loss":2.31}' \ - --outcome success -``` - -### Auto-captured code state - -`run:record` reads the working tree and stores the **repo URL, branch, head commit SHA, and a dirty flag** on the run. Commit before recording so the captured commit matches the code that ran. Opt out with `--no-git`. - -### Bind to a plan or hypothesis - -| Flag | Effect | -| --- | --- | -| `--plan ` | Execute an `experiment:plan`. Atlas evaluates its success criterion and stores `criterion_met`; the run inherits the plan's `run_cluster_key`. | -| `--hypothesis ` | Attach the run to a hypothesis when there is no plan. | -| `--run-cluster-key ` | Fold repeats of the same experiment into one comparable cluster. | - -### Outcomes and failure modes - -| Field | Values | -| --- | --- | -| `--outcome` | `success`, `failure`, `inconclusive` (inferred from `--exit-code` when omitted). | -| `--failure-mode` | `diverged`, `oom`, `data_bug`, `code_bug`, `underperformed`, `other`. | - -Record failures too. A logged `oom` or `diverged` run helps the next agent avoid repeating it. - -### Other flags - -| Flag | Use | -| --- | --- | -| `--config-json` | Run config as JSON or `@file.json`. | -| `--metrics-json` | Numeric metrics as JSON or `@file.json`. | -| `--stdout-tail` | Tail of stdout (secret-scrubbed before storage). | -| `--exit-code` | Process exit code; the outcome is inferred from it. | -| `--no-git` | Skip the automatic code-state capture. | -| `--payload-json` | Full body as JSON; inline flags override its fields. | - -## Offline spool - -If the backend is unreachable, `run:record` writes to `~/.atlas/spool/` and pending entries flush on the next CLI call. Manage the queue directly: - -```bash -atlas run:spool:list # queued entries, oldest first -atlas run:spool:flush # replay; successful posts are removed -atlas run:spool:clear # drop everything without posting -``` - -## Compare runs - -`run:compare` renders a matrix across the runs under a project. It walks descendants (depth ≤ 3), so a project's whole run subtree is in scope. Columns can be node fields or dot-paths into the captured data. - -```bash -atlas run:compare \ - --project able-helm-1359 \ - --cluster resnet50/cifar10/lr-sweep \ - --columns title,config.lr,metrics.val_loss,criterion_met,outcome \ - --sort metrics.val_loss --direction asc --best \ - --format=table -``` - -| Flag | Use | -| --- | --- | -| `--columns` | Node fields (`title`, `outcome`, `failure_mode`, `run_cluster_key`, `criterion_met`, `created_at`) or dot-paths (`config.lr`, `metrics.val_loss`). | -| `--cluster` | Filter to one `run_cluster_key`. | -| `--sort` / `--direction` | Order rows (numeric-aware); `asc` (default) or `desc`. | -| `--best` | Mark the top row after sorting. | -| `--outcome` | Filter to one stored outcome. | -| `--format=table` | Markdown rendering for terminal echo. | - -## Rank with a leaderboard - -`leaderboard` is a `run:compare` preset: sorted in the metric's better direction with the best row marked. - -```bash -atlas leaderboard --project able-helm-1359 --metric metrics.val_loss --direction min -``` - -## Managed executions vs the flight recorder - -These are separate surfaces: - -| You want to... | Use | Namespace | -| --- | --- | --- | -| Record a run that already happened | `run:record`, `run:compare`, `leaderboard` | `run:*` (flight recorder) | -| Start and manage compute on a node | `exec:start`, `exec:list`, `exec:stop` | `exec:*` (managed executions) | - -```bash -atlas exec:start --node nd_... --provider modal -atlas exec:list --node nd_... -atlas exec:stop --node nd_... --execution-id ex_... --yes -``` - -`exec:*` draws down account credit; see [Billing & credits](/atlas/billing). diff --git a/src/content/atlas/skills.mdx b/src/content/atlas/skills.mdx deleted file mode 100644 index 5732d15..0000000 --- a/src/content/atlas/skills.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Atlas skills" -description: "The bundled skills that drive Atlas research workflows from a coding agent." -icon: "book-open" ---- - -Atlas ships nine skills inside `@synsci/atlas`. They are workflow instructions that teach a coding agent how to drive Atlas safely; they are not extra binaries. Run `atlas install` to drop them into the agents on your machine. The router (`atlas`) also covers read-only map commands (`map:tree`, `map:lineage`), while `atlas-search` handles indexed sources, grounded search, and research synthesis. The [CLI overview](/atlas/cli-overview) explains the command families they use. - -## Workflow skills - -| Skill | Trigger / use case | First command | -| --- | --- | --- | -| `atlas-lab` | Doing or continuing actual research in a project, and capturing finished runs. Runs the loop: brief → hypothesis → plan → run → compare → decision. | `atlas brief --project ` | -| `atlas-frontier` | Deciding what to do next, or advancing a frontier autonomously under an explicit objective, budget, and stop condition. Plan-only or auto. | `atlas brief --project ` | -| `atlas-map` | Turning papers, repos, docs, or notes into durable map nodes and evidence, without launching runs. | `atlas node:create` / `atlas library:tree` | -| `atlas-optimize` | Improving a measurable artifact (prompt, config, code) with the GEPA search loop, persisting every candidate as a node. | `atlas optimize:start …` | -| `atlas-autoresearch` | Running an entire refereed campaign from one plain-English goal: baseline → pre-register → search → referee → report. | `atlas autoresearch --goal "…"` | -| `atlas-reproduce` | Turn a paper into a graph. It indexes the paper, finds the code, runs a minimal reproduction, and records paper → claim → setup → result. Missing details become explicit questions, and each answer is saved as a `decision` node. Continue with `atlas autoresearch --project `. | `atlas library:add --type research_paper --url https://arxiv.org/abs/` | -| `atlas-paper` | Drafting a manuscript or report from the recorded graph state. | `atlas map:summary --node ` | - -## Pick the right one - -| User request | Skill | -| --- | --- | -| "Continue the research in this project" / "record this run" | `atlas-lab` | -| "Plan next steps" or "run this frontier autonomously" | `atlas-frontier` | -| "Turn this paper/repo into map state" | `atlas-map` | -| "Optimize this prompt/config against a metric" | `atlas-optimize` | -| "Run the whole campaign from a goal and verify it" | `atlas-autoresearch` | -| "Reproduce this paper" / "does this result hold?" | `atlas-reproduce` | -| "Write this up as a paper" | `atlas-paper` | - -## Verify - -```bash -atlas doctor --format=json # reports the skill count and names -atlas install --dry-run # preview where each skill would land -``` - -`doctor` checks that all nine skills are present in the installed package. The skills ship with the CLI, so do not configure separate downloads. diff --git a/src/content/atlas/web-views.mdx b/src/content/atlas/web-views.mdx deleted file mode 100644 index 04e90e3..0000000 --- a/src/content/atlas/web-views.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "Web app views" -description: "Use cards, orbit, and timeline views to inspect the same research graph." -icon: "layers" ---- - -Everything the CLI writes shows up in the web app at [app.syntheticsciences.ai](https://app.syntheticsciences.ai/atlas). The graph renders three ways, each tuned for a different question, and all colored by node kind. - -## Cards - -The default view. Each node is a kind-colored card showing its title, summary, outcome, and labels. Hypotheses and decisions get first-class card treatment: a hypothesis card surfaces its status (`proposed → testing → supported / weakened / rejected`) and a decision card surfaces what it rests on. Use cards to read and edit the substance of a project. - -## Orbit - -A force-directed layout of the whole graph, colored by kind. Nodes pull into clusters around their parents, so branches, dense experiment clusters, and orphaned work are visible at a glance. Use orbit to understand structure: where the work forked, which hypotheses spawned the most runs, and what is still unconnected. - -## Timeline - -A commit-graph-style view with time-ordered columns, like a git history for research. Runs, decisions, and branches line up by when they happened, so you can trace how an investigation actually unfolded. Use timeline to answer "what did we do, in what order, and why." - -| View | Best for | Layout | -| --- | --- | --- | -| Cards | Reading and editing nodes | Kind-colored cards | -| Orbit | Seeing structure and branches | Force-directed, kind-colored | -| Timeline | Tracing history over time | Commit-graph, time-ordered columns | - -## The app sidebar - -The app navigation reflects the Atlas suite: - -| Item | What it opens | -| --- | --- | -| Home | Account overview and recent activity. | -| Atlas | The suite landing surface. | -| Graphs | The research graph (cards / orbit / timeline). | -| Sources | Indexed knowledge sources. | -| Agent | [OpenScience](/openscience/index), the open-source AI workbench. | -| Compute | Lease a GPU VM and get SSH access. | -| Billing | Credit, quotas, and invoices. | -| Integrations | GitHub, Hugging Face, and W&B connections. | -| Settings | Profile and account settings. | - -## Compute - -GPU compute is available from the **Compute** tab and the CLI. The marketplace aggregates live offers from Lambda Labs, RunPod, Vast.ai, and Prime Intellect. `atlas compute:catalog` shows the cheapest offer per GPU model and accepts filters such as `--gpu h100`, `--provider vast`, `--min-vram 80`, and `--max-price 2.50`. Add `--best` to prefer live stock. `atlas compute:up` launches a VM. With no flags, it selects the cheapest available offer; `--dry-run` previews the selection and price; `--node` attaches the lease to a research node. Use `compute:list`, `compute:ssh`, and `compute:release` to manage it. - -Managed pricing is the provider cost plus a platform fee and is billed from the CLI wallet. Atlas reconciles the charge to the recorded runtime when you release the lease. With a connected provider key, the lease runs on your provider account instead. - -## Publish a view - -Make a node public from the CLI and share the canonical URL: - -```bash -atlas node:share --node nd_root --visibility public -``` - -A public graph viewer can open the exact code behind any node whose commit you pinned with [`repo:capture --pin`](/atlas/reproduction). diff --git a/src/content/openscience/account.mdx b/src/content/openscience/account.mdx new file mode 100644 index 0000000..0c4ace3 --- /dev/null +++ b/src/content/openscience/account.mdx @@ -0,0 +1,65 @@ +--- +title: "Account and workspaces" +description: "Complete sign-in, distinguish project folders from funding workspaces, and manage device access." +--- + +First-run setup requires a Synthetic Sciences account. Ace is optional: after setup you can use your own provider keys, supported subscriptions, or local models. Those model requests use their own connection and do not become Wallet charges because you signed in. + +## Sign in on a new device + +Choose **Continue with Synthetic Sciences** during setup, or run: + +```bash +openscience login +openscience status +``` + +Approve the request in your browser and choose a workspace you belong to. Return to OpenScience to finish setup. On a machine without a browser, use `openscience login --no-browser` and follow the printed instructions in a browser on another device. + +An existing installation can continue to use configured direct provider or local routes when account services are temporarily unavailable. Managed services and shared credentials still need valid account access. This does not bypass the account step on a fresh installation. + +## Know which workspace you are changing + +| Name | What it controls | +| --- | --- | +| Research project | Conversations, working folders, code, inputs, and results in OpenScience. | +| Funding workspace | The Personal or team Wallet, shared connections, and permissions used for managed requests. | +| Dashboard workspace | The account workspace currently selected on the Synthetic Sciences website. | + +Open **Customize → General → Funding workspace** to check the app's selection. **Switch workspace** requires browser approval. Changing the dashboard selection alone does not move an existing app connection. A request in progress keeps its original funding workspace; later requests use the newly approved selection. + +A shared funding workspace does not automatically share local project files, conversations, or Results. Use [Share and hand off research](/openscience/team-workflows) to prepare a research handoff. + +## Connect with a workspace API key + +In the [dashboard](https://app.syntheticsciences.ai/workspaces), choose the intended workspace, open **API Keys**, and select **New key**. Give it a device-specific name and copy the secret while it is displayed. In OpenScience, use **Customize → Models → Ace → Use an API key**. + +The key selects its own funding workspace. It does not inherit a different workspace from a browser login. Current keys use the `osk_` prefix; an existing legacy key may be displayed separately. Treat either as a secret. A key shown in **Provider API keys** belongs in the Ace connection if it was issued by Synthetic Sciences. + +For automated setup, `openscience login --key ` is available. Prefer the app's secret input for interactive use so a real key is not retained in shell history. Store automation credentials in the runner's secret store. + +## Refresh shared access + +Use **Customize → General → Sync now** or: + +```bash +openscience sync +``` + +Your own saved provider key, explicit environment key, or provider sign-in takes precedence over a shared connection. A personal key is not published to your team when you connect it locally. If a shared connection stops working, verify membership and have the workspace administrator check that connection. + +## Sign out or revoke a device + +```bash +openscience logout +``` + +Browser-created device credentials are revoked when sign-out can reach the service. A pasted workspace API key is only forgotten on this device; revoke it in dashboard **API Keys** to stop other clients using it. If remote revocation fails, follow the warning and remove the device through account settings. + +Signing out preserves local research and your separately configured provider access. It does not disable Wallet auto reload, revoke a provider's key, or erase previously shared traces. Manage those independently in [Ace](/openscience/ace), [Models](/openscience/models), and [Privacy and data](/openscience/privacy). + +## Recover access + +If browser approval succeeds but the app stays disconnected, refresh `openscience status` and check that you approved the correct request and workspace. For a missing workspace, check the account you used and the invitation status. A revoked key must be replaced; repeatedly retrying it will not restore access. + +See the [Synthetic Sciences account guides](https://docs.syntheticsciences.ai/#/account/index) for members, billing, Graphs, and Ascent access. diff --git a/src/content/openscience/ace-models.mdx b/src/content/openscience/ace-models.mdx new file mode 100644 index 0000000..abab3d2 --- /dev/null +++ b/src/content/openscience/ace-models.mdx @@ -0,0 +1,53 @@ +--- +title: "Ace model directory" +description: "Browse the reviewed managed model identities and token limits shipped with this documentation version." +--- + +This directory is generated from the reviewed Ace roster shipped with OpenScience. It contains 22 chat models. Live account access, route availability, pricing, and supported controls still come from the managed service. A listed model is not a guarantee that it is available to your account at this moment. + +## Choose and verify a model + +Open **Customize → Models → Rates and limits**, or use the conversation model picker. Confirm the funding label, selected speed, context option, and current rates. Copy an exact CLI identifier from `openscience models --flat`; service model IDs in the table below are not complete CLI provider/model selections. + +Context and maximum output are token limits, not a promise that both can be used at their maximum simultaneously. Runtime metadata and the selected route may constrain them further. A pricing threshold can differ from the context window. GPT-6 models also have a reviewed maximum input of 922,000 tokens. + +## Reviewed chat roster + +| Model | Service model ID | Context tokens | Maximum output tokens | +| --- | --- | ---: | ---: | +| GPT-6 Astra | `openai/gpt-6-astra` | 1,050,000 | 128,000 | +| GPT-6 Sol | `openai/gpt-6-sol` | 1,050,000 | 128,000 | +| GPT-6 Luna | `openai/gpt-6-luna` | 1,050,000 | 128,000 | +| Claude Opus 5.5 | `anthropic/claude-opus-5.5` | 1,000,000 | 128,000 | +| Claude Fable 5.1 | `anthropic/claude-fable-5.1` | 1,000,000 | 128,000 | +| Claude Sonnet 5 | `anthropic/claude-sonnet-5` | 1,000,000 | 128,000 | +| Claude Haiku 4.5 | `anthropic/claude-haiku-4.5` | 200,000 | 64,000 | +| Gemini 3.1 Pro Preview | `google/gemini-3.1-pro-preview` | 1,048,576 | 65,536 | +| Gemini 3.8 Flash | `google/gemini-3.8-flash` | 1,048,576 | 65,536 | +| Grok 4.7 | `x-ai/grok-4.7` | 500,000 | 450,000 | +| GLM 5.3 | `z-ai/glm-5.3` | 1,310,720 | 131,072 | +| GLM 5.3 Flash | `z-ai/glm-5.3-flash` | 1,310,720 | 131,072 | +| DeepSeek V4 Pro | `deepseek/deepseek-v4-pro` | 1,048,576 | 384,000 | +| DeepSeek V4.1 Flash | `deepseek/deepseek-v4.1-flash` | 1,048,576 | 384,000 | +| Qwen 3.8 Max | `qwen/qwen3.8-max` | 1,000,000 | 131,072 | +| Qwen 3.8 Flash Next | `qwen/qwen3.8-flash` | 1,000,000 | 131,072 | +| Kimi K3 | `moonshotai/kimi-k3` | 1,048,576 | 943,718 | +| Kimi K2.7 Code | `moonshotai/kimi-k2.7-code` | 262,144 | 235,929 | +| MiniMax M3 | `minimax/minimax-m3` | 1,048,576 | 512,000 | +| MiMo V2.6 Pro | `xiaomi/mimo-v2.6-pro` | 1,048,576 | 131,072 | +| Muse Spark 1.3 | `meta/muse-spark-1.3` | 1,048,576 | 943,718 | +| Nemotron 3 Ultra | `nvidia/nemotron-3-ultra-550b-a55b` | 262,144 | 16,384 | + +## Effort and Fast mode + +Supported effort choices vary by model and connection. GPT-6 Astra, Claude Opus 5.5, and Claude Fable 5.1 expose Low through Max; Sol and Luna also support a no-reasoning option. The picker is authoritative for the route you selected. Research effort (Normal or Ultra) and worker delegation are separate controls from model reasoning effort. + +Ace Fast for the GPT-6 family uses its separately verified priority route and pricing. Claude and Gemini do not offer Ace Fast. Fast only appears after route metadata confirms support; Refresh options reloads metadata without sending a paid inference request. + +## Images and retired models + +The managed image route is Nano Banana Pro, documented in [Image generation](/openscience/image-generation). Selecting a chat model does not replace the image tool's separate route, requirements, or billing. + +Existing conversations retain their saved model identities. If a prior model is unavailable, select a current model before continuing. Your own provider can expose a different roster; do not infer Ace availability from a provider-key catalog. + +See [Ace and your account](/openscience/ace) for hosting and funding, [Models and providers](/openscience/models) for selection and reasoning, [Pricing](/openscience/pricing) for Wallet rates, and [Usage reports](/openscience/usage) for actual activity. diff --git a/src/content/openscience/ace.mdx b/src/content/openscience/ace.mdx index e008035..4e2f38e 100644 --- a/src/content/openscience/ace.mdx +++ b/src/content/openscience/ace.mdx @@ -3,10 +3,33 @@ title: "Ace and your account" description: "Set up managed access, choose a funding workspace, and manage your Wallet." --- -Ace provides managed models and research search through one purchased Wallet. You do not need separate model-provider keys to use it. +Ace provides managed models and research search using purchased Wallet funds or valid promotional credits. Promotional credit is separate from purchased funds and keeps its expiry. You do not need separate model-provider keys to use it. + +Ace's GPT-6 Astra, Sol, and Luna run on Azure OpenAI Global Standard, and +their Fast mode runs on OpenAI's own priority processing. Claude Opus 5.5, +Fable 5.1, Sonnet 5, and Haiku 4.5 use Anthropic's API directly. Gemini 3.1 +Pro Preview and 3.8 Flash use Google's Gemini API, as does Nano Banana Pro +image generation; choose a `.png` output path for generated images. Graph +search embeddings run on Azure. Grok 4.7 and the other managed models, +including Muse Spark 1.3, continue through OpenRouter. + +Charges use the serving provider's token rates, including cached input and +long-context tiers. Direct routes add no funding or service fee; the OpenRouter +funding fee is already included where it applies. **Customize → Models → Rates +and limits** shows Wallet rates before you start work. Fast mode is available for +the GPT-6 family through OpenAI priority processing; Gemini and Claude have +no Ace Fast mode. Your own provider-key and ChatGPT connections remain +separate. + +The current Ace roster replaces Fable 5 with Fable 5.1, Gemini 3.7 Flash with +3.8 Flash, and Muse Spark 1.2 with 1.3. Existing conversations keep their +saved model identity; choose a current model if an earlier one is no longer +available. A provider key can still expose earlier models independently. Your research project is where you work with conversations and files. Your **funding workspace** is the account workspace that pays for Ace usage. Check both when working across personal and team projects. +Browse the complete [Ace model directory](/openscience/ace-models) for the reviewed chat roster. The live model picker determines availability and current rates. + ## Set up Ace The first-run setup offers Ace as its second step: **Turn on Ace** opens your @@ -16,10 +39,10 @@ up later: 1. Open **Customize → Models** and select **Ace**. 2. Sign in in your browser when prompted. 3. Confirm the workspace you want to use. -4. Add purchased Wallet funds or enable Ace automatic reloads. +4. Confirm available purchased or promotional credits. Add funds if needed; automatic reload is optional. 5. Select an available model and start a conversation. -Review [Pricing and usage](/openscience/pricing) before enabling reloads. Turning on Ace is a $0 authorization; usage is pay as you go. +Review [Pricing and usage](/openscience/pricing) before enabling reloads. Enabling Ace access costs $0; usage is pay as you go. It does not authorize automatic card charges. Auto reload has a separate consent step in Billing. For account setup from a terminal: @@ -31,6 +54,15 @@ openscience wallet show On a machine without a browser, `openscience login --no-browser` prints the sign-in instructions. Complete them from a browser you can access. +### Use an API key instead + +An Ace API key works the way a provider key does: the key alone selects the workspace it is billed to, with no browser round trip and no account signed in on the device. + +1. In the dashboard, choose the workspace the key should bill, open **API Keys**, and select **New key** (`osk_…`). +2. In OpenScience, open **Customize → Models → Ace** and choose **Use an API key**, or run `openscience login --key osk_…`. + +The key may belong to any workspace you are a member of, including one outside the account signed in here; the Ace card labels it (`API key · Lab`), and **Manage Ace** opens that workspace's billing page. A key pasted into **Provider API keys** is redirected here, since it funds a Wallet rather than a provider. Signing out later forgets the key on this device without revoking it: revoke keys in the dashboard. + ## Choose a funding workspace Open **Customize → General → Funding workspace**. If you belong to more than one workspace, use **Switch workspace** and complete the browser approval. @@ -43,9 +75,13 @@ Requests already in progress keep their original funding workspace. Confirm the Open **Wallet** in the Models panel, or visit [billing](https://app.syntheticsciences.ai/billing). -Usage is settled from the provider's reported cost plus a 5.5% funding fee, applied once per request, with no other markup; the card processing fee is shown separately at checkout. While automatic reloads are enabled, a purchased balance below $5 triggers a $20 reload. Account controls let you set a monthly usage limit and turn off future reloads. +Usage is calculated for the route that serves each request. Direct provider routes add no funding or service fee. OpenRouter routes include its funding fee (5.5% by default) once, already included in displayed Wallet rates; the card processing fee is shown separately at checkout. Auto reload is a separate opt-in that requires a saved card. It adds a fixed $20 when purchased funds fall below $5, plus the disclosed processing fee. The reload amount and threshold are fixed; Billing lets you set the monthly automatic-charge limit and turn off future reloads. A managed-usage spending limit is a separate control. Valid purchased or promotional credits can fund requests without auto reload or a saved card. + +Switching to **Keys & subscriptions** changes model access: your keys and subscriptions serve the models they cover. The Wallet still funds what they cannot: a model no key covers, web search when no Firecrawl key is connected, and image generation. Each such call is marked in the trace (`funding: wallet`). Switching does **not** turn off automatic reloads. Use Wallet to change that authorization. + +## Review usage -Switching to **Keys & subscriptions** changes model access. It does **not** turn off automatic reloads. Use Wallet to change that authorization. +Open **Customize → Usage** to filter Managed, API keys, Local models, Subscriptions, and Unclassified activity by dates and model. Export matching daily totals as CSV. Managed records are Wallet charges; user-owned routes are device activity with estimates. See [Usage reports and CSV exports](/openscience/usage). ## Shared connections @@ -61,13 +97,41 @@ openscience sync If access still fails, confirm workspace membership and ask its administrator to check the shared connection. Switching workspaces or signing out removes access supplied by that workspace; it does not remove your own provider accounts. +## Session trace sharing + +While signed in, OpenScience shares session traces by default, including sessions +using your own keys, subscriptions, and local models. Traces include prompts and +model context, provider-visible reasoning and responses, tool inputs and outputs, +and provider-reported usage. Previously saved opt-outs remain in effect. + +Open **Customize → General → Data & privacy → Share session traces** to stop +uploads from this device and discard its queued and rejected records. Account +preferences can disable sharing across devices or exclude user-owned routes. +The device switch does not override an account opt-out. Signing out stops uploads. + +The Delivery row shows queued, acknowledged, and rejected records. Temporary +failures keep stable event IDs for retries; only matching server acknowledgements +remove records. Oversized content is marked as truncated, binary attachments are +represented by metadata, and the bounded local queue can fill while offline. +Logging redacts known credentials, but traces can still contain private research. + +Usage comes from provider responses, including auxiliary title and summary calls. +Missing counts or costs remain unavailable. Reasoning and cached-token fields are +reported details, not additional charges. The trace records preserve reported +costs without replacing them with catalog estimates; these diagnostic records +do not independently verify invoices or change Wallet settlement. Shared trace +usage is separate from the account's usage charts. + +See [Privacy and data](/openscience/privacy) and the [privacy policy](https://openscience.sh/privacy) for retention, account +controls, and deletion. + ## Sign out ```bash openscience logout ``` -Sign-out disconnects this device from your OpenScience account. Your locally saved research remains, and your own provider connections can still be used. To revoke a provider key, remove it separately in **Customize → Models** or at that provider. +Sign-out disconnects this device from your OpenScience account: a browser sign-in's device key is revoked on the server, while a pasted Ace API key is only forgotten locally and stays valid for the account and any other machine using it. Your locally saved research remains, and your own provider connections can still be used. To revoke a provider key, remove it separately in **Customize → Models** or at that provider. Signing out is not a billing cancellation. Manage future Ace reloads in your billing account. diff --git a/src/content/openscience/agents.mdx b/src/content/openscience/agents.mdx index 954eba2..f5b508f 100644 --- a/src/content/openscience/agents.mdx +++ b/src/content/openscience/agents.mdx @@ -52,25 +52,40 @@ In the research controls, delegation determines how readily OpenScience divides These settings guide collaboration. They do not replace your action-approval settings or a service's spending controls. -### Workers: Parallel or Fusion +### Workers -**Workers** chooses how delegated execution is run: +The built-in workers are `explore` (a read-only scout for files, data, code and papers), five specialists built from one template: `ml`, `biology`, `physics`, `chemistry` and `data` (pipelines, processing, coding, visualization), and `general`, a plain worker for a multi-step brief that fits no specialty. Each specialist carries an index of its skill categories and the domain tools those need; the lead dispatches one by name through the Task tool, and independent workers run at the same time with no fixed cap. -- **Parallel** (default): each execute task starts its own worker, and independent workers can run at the same time. -- **Fusion**: the model you selected stays the lead and hands substantial, well-specified work to one persistent worker that runs on the **Worker model** from **Customize → Models**. The same worker is resumed for every execute task in the conversation, so it keeps its history instead of paying to rebuild context on each handoff. The lead keeps the scientific judgment: which claim is tested, whether the data supports it, fitting assumptions, inclusion rules and the conclusions. +You can also hand a job to a worker yourself: type `@` in the composer and pick one (`@explore where is the early-stopping split decided?`). The message becomes that worker's brief, the lead waits for its report, and the worker's session opens from the delegation row. A worker's config can set `hidden: true` to keep it out of the `@` menu while the lead may still dispatch it. -Fusion follows the "sidekick" pattern from Cognition's Devin Fusion: two capable agents with separate, persistent contexts, where the expensive model takes few actions and the cheaper one executes. Choose a cheaper worker model to save on execution; with no worker model set, Fusion still keeps one persistent worker but on the same model as the lead. The Tools menu shows the pair, delegated task cards show the handoff number and lineage, and the session cost readout includes what the worker spent. Each turn may make a bounded number of handoffs (six by default); the worker never publishes results or launches paid compute; those stay with the lead. +A worker runs on its own configured model when the agent has one, otherwise on the **Worker model** from **Customize → Models**, otherwise on the lead's model. No built-in agent has a model in code; the recommended configuration is documented below. Workers work in the lead's own directory: the files they write there are the deliverables, and the lead reads them directly. The lead writes a self-contained brief with a definition of done, waits for the result (returned once, in a `` envelope with a `task_id` that can resume the same worker), and integrates it; checking the lead's own output is never delegated. A worker started in the background returns immediately and wakes the lead with its result when it finishes. Workers cannot dispatch workers unless `subagent_depth` in `openscience.json` allows deeper nesting (default 1). -Open a delegated task to inspect its tool activity and current assignment. Reused workers -keep their earlier conversation, while the heading identifies their active assignment. -Stopping the lead also cancels its active delegated work, including workers preparing -to start. A stopped task's saved files and recorded tool results remain available. +A delegated task shows as one line (what it is doing, which agent, its state and elapsed time) and streams nothing while it runs; open it for the result, its saved Results and **Open agent**, which shows the worker's own conversation. Stopping the lead also cancels its active delegated work. A stopped task's saved files and recorded tool results remain available. -Saved worker Results carry immutable artifact and version IDs back to the lead. -The lead can read these versions without access to the worker's private scratch. Only the latest assistant message's text after its final tool call counts as the -handoff; earlier progress text cannot make an unfinished worker look complete. -An empty handoff remains incomplete, even if the worker saved files. +result; earlier progress text cannot make an unfinished worker look complete. A +result without a Verification section (the command, its exit code, what it +proves) is a claim, and the lead is told so. + +#### Recommended models + +Put the models you want each agent to use in `openscience.json`; nothing is hard-coded: + +```json +{ + "model": "openai/gpt-6-astra", + "agent": { + "explore": { "model": "google/gemini-3.8-flash" }, + "ml": { "model": "openai/gpt-6-sol", "variant": "high" }, + "biology": { "model": "openai/gpt-6-sol" }, + "physics": { "model": "openai/gpt-6-sol" }, + "chemistry": { "model": "openai/gpt-6-sol" }, + "data": { "model": "openai/gpt-6-sol" } + } +} +``` + +A worker on a different model than the lead uses its own `variant` (reasoning effort); on the lead's model it inherits the lead's. Add your own specialist the same way, with `mode: "subagent"`, `skills: ["", ...]` for its domain index and a `permission` rule per domain tool it may use without a skill. Handoffs retain command receipt references and failures. A shell exit of zero describes the outer process; it does not establish that nested tests passed or @@ -97,7 +112,7 @@ Use `/goal` for an objective you want to pursue across multiple steps: a figure, a methods note, and a list of unresolved limitations. ``` -Use `/status` to inspect progress. `/checkpoint` captures a recovery point; `/handoff` saves a continuation note and compacts the conversation. Commands offered as skills must be enabled in your setup. +The session header shows progress and context usage. `/checkpoint` captures a recovery point; `/handoff` saves a continuation note and compacts the conversation. Commands offered as skills must be enabled in your setup. A persistent goal does not mean OpenScience can keep working while your computer or app is off. Save a checkpoint before interrupting a long task. @@ -127,6 +142,8 @@ Review the analysis plan and identify unsupported assumptions. Explain each concern and suggest a check before the analysis runs. ``` -Save it as `analysis-reviewer.md` in the agent directory. Select it with `--agent analysis-reviewer`. A `primary` agent can lead a session, a `subagent` is for delegated tasks, and `all` supports both. +Save it as `analysis-reviewer.md` in the agent directory. Select it with `--agent analysis-reviewer`, or in the app: once a second primary agent exists, an agent chip appears beside the model control in the composer, and `Tab` in an empty composer cycles through the primary agents. A `primary` agent can lead a session, a `subagent` is for delegated tasks and the `@` menu, and `all` supports both. + +Other frontmatter options: `model` (`provider/model-id`; a worker without one uses the lead's model), `temperature` and `top_p`, `steps` (a cap on agentic iterations, after which the agent is asked to summarize and list what remains), `color` (a hex value or a theme color such as `accent`), `disable`, and `permission.task` globs that decide which workers the agent may dispatch. The deprecated `tools:` map still loads; `openscience agent create` writes `permission:` rules. Custom definitions change the agent's instructions and permitted actions. Test a new profile on a small task before relying on it. diff --git a/src/content/openscience/api.mdx b/src/content/openscience/api.mdx index 7cfe128..2beaa01 100644 --- a/src/content/openscience/api.mdx +++ b/src/content/openscience/api.mdx @@ -71,6 +71,8 @@ Use a runtime that supports this option; see [session workspaces](/openscience/s An identical `requestID` in the same session returns the original receipt, including after completion. A changed prompt or model with that ID returns HTTP 409. Omit the ID only when duplicate admission after an uncertain network result is acceptable. Advanced clients can supply a native `messageID`; ordinary integrations should let the server generate it and use their own external `requestID`. +A prompt sent while the session has a live run joins that run: the message is added to the conversation, the agent reads it on its next step and answers it in the same run, and the response is the live run's receipt (its `runID`). A retry of that follow-up with the same `requestID` replays the run it joined, including after it ends. There is no separate queue to manage or flush. + Use **exactly one** of `message` or `parts`. Parts support ordinary text, file attachments, agent mentions, conversation references, and explicit subtasks using the generated session input types. Internal synthetic text and system/agent overrides are excluded. Optional model, variant, tier, context, delegation, and delegation settings survive admission. Run states are `accepted`, `running`, `completed`, `failed`, `cancelled`, and `interrupted`. A completed run means the agent turn finished; it does not prove the science is correct or that a detached compute job has completed. Inspect saved Results, job delivery state, and native verification separately. diff --git a/src/content/openscience/automation.mdx b/src/content/openscience/automation.mdx index 2505ee2..f378269 100644 --- a/src/content/openscience/automation.mdx +++ b/src/content/openscience/automation.mdx @@ -13,17 +13,31 @@ openscience run --deny-prompts --format json "Summarize the project README" > ru This emits newline-delimited JSON. A rejected permission request can stop the run with exit code 3. -For work you have already reviewed and authorized, `--auto-approve` approves the run's permission requests and disables delegation. It is mutually exclusive with `--deny-prompts`. +For work you have already reviewed and authorized, `--auto-approve` approves the run's permission requests, answers any question the agent asks with its recommended option, and continues past a denied tool call instead of ending the run. Delegation stays on: worker sessions stream into the same output. It is mutually exclusive with `--deny-prompts`. ```bash openscience run --auto-approve --format json "Run the existing data validation script and report failures" > run.jsonl ``` +Four flags shape a headless run: + +| Flag | Effect | +| --- | --- | +| `--delegation off\|light\|standard\|high` | How freely the lead dispatches workers; the default is the saved preference. | +| `--worker-model provider/model` | The model workers run on when their agent has none configured. | +| `--autonomy interactive\|balanced\|autonomous` | How the lead treats decision points; `--auto-approve` defaults to `autonomous`. | +| `--deadline ` | A wall-clock budget. The agent sees the `Time budget` in its environment, gets a reminder at 50% and at 85% that states the time used, and is asked to continue when time remains and named outputs are missing. | + +```bash +openscience run --format json --auto-approve --workspace project \ + --delegation standard --deadline 600 -- "Fit the model; write results/fit.csv and results/report.md" +``` + Use a clearly scoped project and request. The command's ability to run still depends on installed tools, account access, and applicable policy. ## Read events -Each event has `type`, `timestamp` in milliseconds, and `sessionID`. +Each event has `type`, `timestamp` in milliseconds, and `sessionID`. Events from a worker session carry that session's id and a `parentID` naming the session that dispatched it; root events have no `parentID`. | Event | Main content | | --- | --- | @@ -31,10 +45,11 @@ Each event has `type`, `timestamp` in milliseconds, and `sessionID`. | `step_start` / `step_finish` | A model step; finished steps include usage. | | `text` | A completed text part. | | `reasoning` | A completed readable reasoning part, when available. | -| `tool_use` | A completed or failed tool call; inspect `part.state.status`. | +| `tool_use` | A completed or failed tool call; inspect `part.state.status`. A `task` result carries the worker's answer in a `` envelope. | | `permission` | The permission request and reply. | +| `question` | A question the run answered on the agent's behalf, with the answers. | | `error` | An error name and data. | -| `done` | Final `status`, `exitCode`, `tokens`, and `cost`. | +| `done` | Final `status`, `exitCode`, the root session's `tokens` and `cost`, and `children`: one entry per worker session with its `agent`, `model`, `tokens` and `cost`. | Example completion event: diff --git a/src/content/openscience/autoresearch.mdx b/src/content/openscience/autoresearch.mdx new file mode 100644 index 0000000..5830cdb --- /dev/null +++ b/src/content/openscience/autoresearch.mdx @@ -0,0 +1,58 @@ +--- +title: "Autoresearch" +description: "Let a study hill-climb a metric over many runs while you watch: tracked metrics, a baseline, ideas ranked by expected value, and a ledger of what was kept." +--- + +The Autoresearch pane sits beside Files, Terminal and Compute. Each study has a tab: its score (the best value and how far it moved from the baseline), the climb across runs, the runs with their training curves, the idea queue, the lessons and the activity. A study runs experiments in a loop: one metric, a baseline, a queue of ideas, and a ledger of what was kept or reverted. + +## Track a run + +Any script that OpenScience runs can report metrics. Import the tracker and log the numbers you want to see: + +```python +import openscience_track as track + +run = track.init(project="lora-vs-full", name="lora-r16", config={"lr": 1e-4, "rank": 16}) +for step, batch in enumerate(loader): + loss = train_step(batch) + if step % 50 == 0: + track.log({"train_loss": loss, "lr": lr}, step=step) +track.summary["val_loss"] = evaluate() +track.finish() +``` + +Scripts written for `wandb` work unchanged inside a study: `import wandb` resolves to a shim that forwards to the tracker. No account, no network, no dependency: inside a compute job each record is one marked line on the job's output, which OpenScience reads back and stores in a per-project SQLite file under the data root. The Compute pane's log view and the model's `compute_job logs` never show those lines. + +Runs appear under their study as they log. Click a run for its configuration, summary values and one chart per metric; toggle runs on the comparison chart with the coloured squares, pick the metric, smooth or switch to a log scale. + +## Start a study + +Ask for one in plain words: + +```text +Start an autoresearch study on train.py: minimize val_loss, baseline first, +at most 2 runs at a time on this machine, kill a run after 1 hour or if +val_loss plateaus for 500 steps, stop after 20 runs or 8 hours. +``` + +The agent agrees the objective, creates the study, proposes the baseline and the first ideas ranked by expected value, and starts the baseline through the compute permissions you already use. From then on: + +- OpenScience follows each run's metrics, ends runs that break the kill criteria, and when a run finishes wakes the session with a **Study update** that reports the metric against the baseline. You can read every wake-up in the transcript. +- The agent records a verdict for each run (kept or reverted, with its analysis and any lesson), queues the ideas the result suggests, and starts the next one. Exactly one run per idea. +- Pause, Resume and Halt sit beside the score. Halt cancels live runs. The budget you set pauses the study and asks for a conclusion when it is reached; a study always has its own budget, agreed when it starts, never one inherited from an earlier study. +- **steer** adds a standing directive ("only vary the optimizer from now on") that wakes the agent immediately and stays in its instructions until you retire it. Typing in the chat works too; a directive is the version that survives the next fifty runs. +- The loop keeps itself honest: the agent is asked for more ideas when fewer than three are queued, for a different kind of idea after four runs without progress, and for a step-back review every six runs. Short runs are waited on inside a turn; wake-ups are for runs that outlast one. +- `study.md`, `ideas.md`, `results.tsv` and `lessons.md` are rendered into the working folder as the study advances, in the shape of Karpathy's autoresearch loop, so the record is readable without the app and travels with the project. + +Studies run on the local machine (one run per GPU when `nvidia-smi` is present), on a saved SSH or scheduler host, or on Modal. Local and SSH runs chart live; a Modal run's metrics arrive when its log is delivered at the end. The compute permissions are unchanged: a study starts runs the way you would, with the same approvals, under your Independence setting. With the review gate on (the default), the agent has a read-only `explore` worker critique the training and evaluation code before the baseline runs and fixes anything marked blocking. Approving a Modal study also grants a time allowance equal to its hour budget for the jobs that follow the runs (the final refit, an external baseline), so those do not ask again. A run whose dispatch fails before its command executes (an input over the upload limit, a file edited while a dispatch was in flight) returns its idea to the queue instead of spending it. + +## Write it up + +**Write up** beside the score starts a turn that reads the ledger and the tracked runs and drafts the results: baseline, best configuration, the ablations that mattered, and the figures the data supports. Kept runs are the claims; reverted runs are the ablations that keep them honest. + +## Tools the agent uses + +- `study`: create, status, propose, start, record, drop, conclude. +- `experiments`: runs, keys, series, compare. + +Both are ordinary tools with their own permission entries (`study` is contained, `experiments` is read-only). Runs still go through `compute_job`. diff --git a/src/content/openscience/built-in-tools.mdx b/src/content/openscience/built-in-tools.mdx index 368d030..694910f 100644 --- a/src/content/openscience/built-in-tools.mdx +++ b/src/content/openscience/built-in-tools.mdx @@ -3,7 +3,9 @@ title: "Built-in research tools" description: "See the operations available to the agent and learn how to request useful, checkable work." --- -You normally use these tools through a conversation rather than calling them yourself. State the input, intended output, and limits. Tool availability depends on the agent, model, configuration, and project permissions. +You normally use these tools through a conversation rather than calling them yourself. State the input, intended output, and limits. + +Which tools the agent sees follows permissions, not the wording of your request. Research starts from a default set (`bash`, `read`, `glob`, `grep`, `edit` and `write` or `apply_patch` for GPT-family models, `webfetch`, `research_search` when a search provider is connected, `literature`, `recall`, `todowrite`, `task`, `skill`, `question` in interactive clients, `python`, `compute_job`, `artifact`). Everything else appears when a loaded skill declares it in `allowed-tools`, when the agent's configuration allows it by name, or when a specialist worker carries it: `r`, the biological query tools, the `science_*` connectors, `experiments` and `study`, `generate_image`, `lsp`, `codesearch`, and remote compute. ## Read, search, and edit files @@ -24,7 +26,6 @@ Give exact paths for important inputs, and preserve original data. Use [Code and | --- | --- | --- | | Python execution | `python` | [Run calculations, inspect values, and save plots](/openscience/python-r). | | R execution | `r` | [Analyze with R and save reproducible scripts](/openscience/python-r). | -| Scientific readiness and supported execution | `scientific_capability` | [Check the scientific catalog and setup state](/openscience/tool-catalog). | | Planned and detached compute jobs | `compute_job` | [Plan, start, inspect, cancel, and recover outputs](/openscience/jobs). | | Supported provider account/status checks | `provider_compute` | [Connect remote resources and understand scope](/openscience/remote-compute). | @@ -40,6 +41,8 @@ wait for approval before launching the job. | --- | --- | --- | | Web, research, news, and developer search | `research_search` | [Choose source, filters, and content depth](/openscience/research-search). | | Read a known web URL | `webfetch` | [Read and verify source documents](/openscience/documents). | +| Find and read papers | `literature` | [Search OpenAlex and arXiv together, then read the full text by DOI or arXiv id](/openscience/literature-review#how-papers-are-found-and-read). | +| Recover something seen earlier in this session | `recall` | Searches every earlier message, tool result and saved tool output by regular expression, including turns compaction summarized away. | | Search technical reference material | `codesearch` | [Use source-grounded code and repository workflows](/openscience/code). | | Discover scientific databases | `science_list_dbs` | [Choose a source by domain](/openscience/database-workflows). | | Search a scientific database | `science_search` | [Use native queries and source identifiers](/openscience/database-workflows). | @@ -67,7 +70,7 @@ OpenScience can track work, ask questions, delegate a bounded task, load a skill | Capability | How to request it | | --- | --- | -| Track steps and progress | Define a [plan or goal](/openscience/planning), then inspect `/status`. | +| Track steps and progress | Define a [plan or goal](/openscience/planning); the plan panel tracks the steps. | | Ask about missing information | Choose the appropriate [independence setting](/openscience/agents) and state important uncertainties. | | Delegate independent work | Enable delegation and give separable questions with a shared output format. | | Load a procedure | Select a [skill](/openscience/skills) and describe its task. | diff --git a/src/content/openscience/capabilities.mdx b/src/content/openscience/capabilities.mdx index 4d4dd1d..d30bc2e 100644 --- a/src/content/openscience/capabilities.mdx +++ b/src/content/openscience/capabilities.mdx @@ -27,6 +27,7 @@ Use this map to find the relevant workflow. Availability depends on your model's | [Machine learning](/openscience/machine-learning) | Dataset, target, split, evaluation plan | Baselines, metrics, model artifacts, and an experiment comparison. | | [Genomics](/openscience/genomics) | Sequences, reads, variants, annotations, or single-cell data | Quality checks, derived tables, visual inspection, and reproducible analysis. | | [Molecular research](/openscience/molecular-research) | Molecules, structures, sequences, or assay data | Descriptors, structural views, or supported predictions and simulations. | +| [NVIDIA BioNeMo NIMs](/openscience/tool-catalog) | Sequences, structures, ligands, and your NVIDIA API key | Boltz-2, DiffDock, Evo 2, GenMol, MolMIM, MSA Search, OpenFold2, OpenFold3, ProteinMPNN and RFdiffusion runs with hashed artifacts, one approval per dispatch. | | [Reproduction](/openscience/reproduction) | Paper, code, data, and target result | A bounded reproduction, comparison with the claim, and a record of differences. | | [Compute jobs](/openscience/jobs) | Command, resources, inputs, and expected outputs | Local or connected remote execution with status and delivered files. | diff --git a/src/content/openscience/commands.mdx b/src/content/openscience/commands.mdx index 3db1c49..1c3d85d 100644 --- a/src/content/openscience/commands.mdx +++ b/src/content/openscience/commands.mdx @@ -30,7 +30,7 @@ Run `openscience --help` or `openscience --help` for the options suppo | `openscience import ` | Import a session export. | | `openscience stats` | Show local usage statistics. | -Important `run` options: `--model`, `--agent`, `--effort`, `--variant`, `--file`, `--title`, `--command`, `--format json`, `--bare`, `--attach`, `--deny-prompts`, and `--auto-approve`. +Important `run` options: `--model`, `--agent`, `--effort`, `--variant`, `--file`, `--title`, `--command`, `--format json`, `--bare`, `--attach`, `--workspace`, `--delegation`, `--worker-model`, `--autonomy`, `--deadline`, `--deny-prompts`, and `--auto-approve`. See [Sessions](/openscience/sessions) for meanings and [Automation](/openscience/automation) for JSON events and exit codes. @@ -67,6 +67,7 @@ See [Sessions](/openscience/sessions) for meanings and [Automation](/openscience | --- | --- | | `openscience login` | Sign in for Ace and account connections. | | `openscience login --no-browser` | Print browser sign-in instructions. | +| `openscience login --key ` | Connect an existing workspace key; keep the secret out of shell history. | | `openscience logout` | Sign this device out. | | `openscience status` | Show account, model access, and Wallet; alias `whoami`. | | `openscience sync` | Refresh shared workspace connections. | @@ -109,7 +110,7 @@ See [Sessions](/openscience/sessions) for meanings and [Automation](/openscience | Command | Purpose | | --- | --- | -| `openscience upgrade [version]` | Update the CLI. | +| `openscience upgrade [version]` | Update the CLI. On a copy that came with the desktop app, it points at the app's own updater instead. | | `openscience uninstall --dry-run` | Preview removal. | | `openscience uninstall` | Uninstall while keeping work and settings by default. | | `openscience debug paths` | Show resolved application directories. | diff --git a/src/content/openscience/configuration.mdx b/src/content/openscience/configuration.mdx index ee29430..09a3277 100644 --- a/src/content/openscience/configuration.mdx +++ b/src/content/openscience/configuration.mdx @@ -51,11 +51,28 @@ Use `/check-data data/samples.csv` in the workspace, or `openscience run --comma | `mcp` | External tool connections. | | `plugin` | Plugin packages or local module URLs. | | `permission` | Action rules such as `ask`, `allow`, and `deny`. | +| `agent.` | Per-agent `model`, `variant`, `skills` (categories for a specialist's domain index), `prompt`, `permission`. A rule that names a tool offers it to that agent without a skill. | +| `subagent_depth` | How many levels of workers may nest; default `1` (only the lead dispatches). | +| `harness` | Switches for the harness units, all on by default: `redirect`, `deliverables`, `budget`, `cost` (or `{ "max_usd": n }` for a soft spend ceiling), `headless-policy`, `durable-jobs`, `workers`. | | `server.port` | Port for the local workspace or server. | | `autoupdate` | Update preference: `true`, `false`, or `"notify"`. | Provider and model identifiers must match the configured catalog. Use `openscience models --flat` to find them. +### Harness units + +Each unit delivers one piece of context at a precise point in the loop and can be switched off with `"harness": { "": false }`: + +| Unit | What it does | +| --- | --- | +| `redirect` | When the same tool failure repeats three times (or the model loops on text), inject one strategy-change message instead of stopping; a second trip stops the turn. | +| `deliverables` | When the first request names its output files, check each named file before the turn ends (present, non-empty, parses, no NaN/Inf, no placeholder text, no duplicate ids) and list the failures once; two rounds at most. | +| `budget` | Show CPUs and memory (from the container's cgroup) and, with a deadline, the time budget and elapsed time in the environment block; remind at 50% and 85%; ask to continue when time remains and deliverables fail. | +| `cost` | Show spend so far beside the time budget; an optional soft ceiling adds a wrap-up reminder, never a hard stop. | +| `headless-policy` | In `openscience run --auto-approve`, continue past denied tool calls and answer questions with their recommended option. | +| `durable-jobs` | Keep tool hints consistent with what is offered: the truncation hint suggests a worker only when delegation is on. | +| `workers` | Stream child-session events in headless runs and roll their usage into `done`. | + ## Scope and overrides Global configuration supplies defaults; project configuration can override project-specific settings. Options are combined, so adding a project setting does not mean every global setting is removed. diff --git a/src/content/openscience/context.mdx b/src/content/openscience/context.mdx index e6dc050..86d119c 100644 --- a/src/content/openscience/context.mdx +++ b/src/content/openscience/context.mdx @@ -7,11 +7,7 @@ A conversation has a finite context window. OpenScience can summarize earlier wo ## Inspect context usage -Use `/context` to inspect the current context composition, available capacity, and compaction state. Large attachments, long tool outputs, instructions, and conversation history all contribute to the material available to the model. - -```text -/context -``` +The token counter in the session header shows how much of the model's context the conversation occupies; open it for the composition. Large attachments, long tool outputs, instructions, and conversation history all contribute to the material available to the model. Context capacity differs by model. Switching models can change how much material fits; see [Models](/openscience/models). @@ -32,6 +28,12 @@ OpenScience automatically compacts a conversation as it approaches the model's u If the model offers a smaller context-window choice, that choice is retained through compaction and continuation. Automatic compaction uses that selected capacity, bounded by the model's supported limits, rather than silently expanding back to the full window. +When a model prices long prompts in tiers (GPT-6 Astra doubles every input rate past 272K tokens), the default budget is the first pricing boundary, so the conversation compacts a little before it crosses into the higher tier and each later step pays the lower rate on its whole prompt. Choose **Full** in the model's context options to allow the whole window instead; the choice is kept per model. + +Old tool results are pruned only when the provider's prompt cache has gone cold (thirty minutes without a request) or when capacity requires it. Pruning rewrites earlier context, which the provider then re-reads at full price, so a wake-up inside the cache window keeps its prefix intact. Up to twenty recent images travel in full with each request; past that, the older half are released together and become placeholders that can be read again (`compaction.recentImages`). + +A summary request is built from the conversation's own header, system blocks and tools (offered, not callable), so the provider serves the material it summarizes from the cache the conversation already wrote; a configured `agent.compaction.model` that differs from the conversation's model takes a standalone request instead. Reasoning is replayed for the work since your last message; earlier turns' reasoning is left out of requests, as the visible transcript carries the decisions. + Old `compaction.threshold` and warning-level preferences are ignored. If you explicitly set `compaction.auto` to `false` in configuration, use `/compact` before the conversation becomes too large. ## Save a checkpoint @@ -59,13 +61,13 @@ exist, summarize the current state, and continue with the next step. ## Choose the right recovery action -| Need | Action | -| --- | --- | -| More space in the same discussion | Compact with a clear focus. | -| A local recovery point | Save a checkpoint and review its scope. | -| A human-readable continuation note | Write a handoff file. | -| A copy of conversation history | Use [session export](/openscience/sessions). | -| A durable deliverable | Save a [Result](/openscience/results) and its supporting files. | -| Return to an earlier supported turn | Use Undo and review affected changes. | +| Need | Action | +| ----------------------------------- | --------------------------------------------------------------- | +| More space in the same discussion | Compact with a clear focus. | +| A local recovery point | Save a checkpoint and review its scope. | +| A human-readable continuation note | Write a handoff file. | +| A copy of conversation history | Use [session export](/openscience/sessions). | +| A durable deliverable | Save a [Result](/openscience/results) and its supporting files. | +| Return to an earlier supported turn | Use Undo and review affected changes. | Commands surfaced as skills need those skills enabled. Check [Slash commands](/openscience/slash-commands) if an action is not offered in the picker. diff --git a/src/content/openscience/custom-providers.mdx b/src/content/openscience/custom-providers.mdx index 8b4e7e3..db23ee5 100644 --- a/src/content/openscience/custom-providers.mdx +++ b/src/content/openscience/custom-providers.mdx @@ -98,12 +98,12 @@ Provider options support request deadlines in milliseconds: | Option | Default | | --- | --- | -| `connectTimeout` | 300000 (5 minutes): waiting for response headers; disabled by default for local endpoints. | -| `idleTimeout` | 1800000 (30 minutes) for remote endpoints; reset by every response-body chunk and disabled by default for local endpoints. | +| `connectTimeout` | 300000 (5 minutes) waiting for response headers; 600000 (10 minutes) for the managed Ace gateway, which sends headers only once the upstream body begins; disabled by default for local endpoints. | +| `idleTimeout` | 600000 (10 minutes) for remote endpoints, including the managed Ace gateway; reset by every response-body chunk and disabled by default for local endpoints. | | `outputIdleTimeout` | Disabled; optionally bound the wait for readable output or tool-call activity. | | `timeout` | No total-duration limit by default. | -Active remote responses keep running because keepalives and streamed private reasoning reset the body-activity deadline. Set `idleTimeout` to `false` if a remote provider legitimately stays byte-silent for longer than 30 minutes. Use **Stop** to cancel your wait. To opt into a twenty-minute readable-output deadline, merge an override into that provider's options: +Active remote responses keep running because keepalives and streamed private reasoning reset the body-activity deadline. Set `idleTimeout` to `false` if a remote provider legitimately stays byte-silent for longer than ten minutes. Use **Stop** to cancel your wait. To opt into a twenty-minute readable-output deadline, merge an override into that provider's options: ```json { diff --git a/src/content/openscience/databases.mdx b/src/content/openscience/databases.mdx index 1e2a24a..376a49f 100644 --- a/src/content/openscience/databases.mdx +++ b/src/content/openscience/databases.mdx @@ -41,16 +41,16 @@ These are built-in database connections. Use [Connectors and MCP](/openscience/c | Source and documentation | Identifier | Records and uses | Declared formats | | --- | --- | --- | --- | | [ArrayExpress / BioStudies](https://www.ebi.ac.uk/biostudies/arrayexpress) | `arrayexpress` | Functional genomics experiments (microarray & sequencing) archived on EMBL-EBI BioStudies. | Structured record | -| [DepMap](https://depmap.org) | `depmap` | Cancer Dependency Map: released CRISPR/RNAi, omics, and drug-sensitivity dataset metadata. | Structured record | +| [DepMap](https://depmap.org) | `depmap` | Cancer Dependency Map — released CRISPR/RNAi, omics, and drug-sensitivity dataset metadata. | Structured record | | [Ensembl](https://www.ensembl.org) | `ensembl` | Genes, transcripts, and cross-references by symbol or Ensembl stable id. | `fasta` | | [Expression Atlas](https://www.ebi.ac.uk/gxa) | `expression-atlas` | Bulk gene & protein expression across tissues, conditions, and species (EMBL-EBI GXA). | Structured record | | [gnomAD](https://gnomad.broadinstitute.org) | `gnomad` | Population allele frequencies (genome/exome) for genes and variants. | Structured record | -| [GTEx](https://gtexportal.org) | `gtex` | Genotype-Tissue Expression: median gene expression across human tissues. | Structured record | +| [GTEx](https://gtexportal.org) | `gtex` | Genotype-Tissue Expression — median gene expression across human tissues. | Structured record | | [MyGene.info](https://mygene.info) | `mygene` | Gene annotation lookup (symbol, name, Entrez/Ensembl ids) across species. | Structured record | | [MyVariant.info](https://myvariant.info) | `myvariant` | Aggregated variant annotation (dbSNP, ClinVar, CADD, dbNSFP) by HGVS or rsID. | Structured record | | [NCBI dbSNP](https://www.ncbi.nlm.nih.gov/snp) | `dbsnp` | Reference SNP (rsID) records: alleles, position, function class, and clinical significance. | Structured record | | [NCBI Gene](https://www.ncbi.nlm.nih.gov/gene) | `ncbi-gene` | Gene records (symbol, aliases, locus, summary) from NCBI Entrez Gene. | Structured record | -| [NCBI GEO](https://www.ncbi.nlm.nih.gov/geo/) | `geo` | Gene Expression Omnibus: functional genomics Series, DataSets, and platforms. | Structured record | +| [NCBI GEO](https://www.ncbi.nlm.nih.gov/geo/) | `geo` | Gene Expression Omnibus — functional genomics Series, DataSets, and platforms. | Structured record | | [Open Targets](https://platform.opentargets.org) | `opentargets` | Target-disease-drug associations for drug target identification. | Structured record | | [Single Cell Expression Atlas](https://www.ebi.ac.uk/gxa/sc) | `single-cell-atlas` | Single-cell RNA-seq experiments with cell-type expression across species (EMBL-EBI GXA sc). | Structured record | | [UCSC Genome Browser](https://genome.ucsc.edu) | `ucsc` | Search genome assemblies for genes/positions and retrieve reference sequence. | Structured record | @@ -84,7 +84,7 @@ These are built-in database connections. Use [Connectors and MCP](/openscience/c | Source and documentation | Identifier | Records and uses | Declared formats | | --- | --- | --- | --- | | [AlphaFold DB](https://alphafold.ebi.ac.uk) | `alphafold` | AlphaFold-predicted protein structures with per-residue confidence (pLDDT). | `pdb`, `cif` | -| [PDBe](https://www.ebi.ac.uk/pdbe) | `pdbe` | Protein Data Bank in Europe: 3D structures with EBI annotations and cross-references. | `cif` | +| [PDBe](https://www.ebi.ac.uk/pdbe) | `pdbe` | Protein Data Bank in Europe — 3D structures with EBI annotations and cross-references. | `cif` | | [RCSB PDB](https://www.rcsb.org) | `rcsb-pdb` | Experimentally determined 3D structures of proteins, nucleic acids, and complexes. | `pdb`, `cif` | | [SIFTS](https://www.ebi.ac.uk/pdbe/docs/sifts) | `sifts` | UniProt↔PDB residue-level structure mappings (best PDB structures per protein). | Structured record | diff --git a/src/content/openscience/docs.json b/src/content/openscience/docs.json index 5b536a1..3c67387 100644 --- a/src/content/openscience/docs.json +++ b/src/content/openscience/docs.json @@ -15,7 +15,7 @@ }, { "group": "Models and account", - "pages": ["models", "ace", "pricing", "local-models", "custom-providers"] + "pages": ["account", "models", "ace", "ace-models", "pricing", "usage", "local-models", "custom-providers"] }, { "group": "Plan and continue", @@ -23,7 +23,7 @@ }, { "group": "Personalize and get help", - "pages": ["preferences", "keyboard-shortcuts", "troubleshooting", "faq"] + "pages": ["preferences", "privacy", "keyboard-shortcuts", "troubleshooting", "faq"] } ] }, @@ -54,7 +54,7 @@ }, { "group": "Run substantial work", - "pages": ["compute", "jobs", "remote-compute"] + "pages": ["compute", "jobs", "remote-compute", "autoresearch"] } ] }, diff --git a/src/content/openscience/experiment-tracking.mdx b/src/content/openscience/experiment-tracking.mdx index 64394a5..0ef02d3 100644 --- a/src/content/openscience/experiment-tracking.mdx +++ b/src/content/openscience/experiment-tracking.mdx @@ -53,6 +53,6 @@ A lesson about one dataset or environment should not be generalized to unrelated ## Review the investigation -Use `/status` and ask for the objective, active stage, completed checks, trials, failures, required outputs, and unresolved questions. Before handing off, save a readable report and [continuation note](/openscience/context). +Ask for the objective, active stage, completed checks, trials, failures, required outputs, and unresolved questions. Before handing off, save a readable report and [continuation note](/openscience/context). Use [Compute jobs](/openscience/jobs) for execution, [Reproduction](/openscience/reproduction) for matching an existing result, and [Saved Results](/openscience/results) for retaining evidence files. diff --git a/src/content/openscience/extensions.mdx b/src/content/openscience/extensions.mdx index b4807aa..91fc1f5 100644 --- a/src/content/openscience/extensions.mdx +++ b/src/content/openscience/extensions.mdx @@ -100,6 +100,11 @@ openscience acp --cwd /absolute/path/to/research-project Configure that executable and its arguments in your editor's agent settings. The editor supplies the interactive interface; your model connections and project configuration still apply. +Editors can list and resume sessions and select a connected model, including its +reasoning variants, through ACP session configuration. Older editors using +`session/set_model` remain supported. Supplied MCP servers can use HTTP, +SSE, or stdio; forwarding MCP messages over the ACP connection is not supported. + Refer to the editor's documentation for its exact configuration format. ## Contribute to OpenScience diff --git a/src/content/openscience/faq.mdx b/src/content/openscience/faq.mdx index 90d80e0..2435a84 100644 --- a/src/content/openscience/faq.mdx +++ b/src/content/openscience/faq.mdx @@ -9,11 +9,11 @@ The workbench is free and open source under Apache-2.0. Models, compute, and ext ## Do I need an OpenScience account? -Not for your own provider API key, supported provider sign-in, or local models. Sign in to use Ace and shared account-workspace connections. +Yes for first-run setup. Ace is optional, and your own provider keys, supported subscriptions, and local models remain direct. An already configured installation can continue using those routes during an account-service outage. See [Account and workspaces](/openscience/account). ## Is Ace a subscription? -Ace has no monthly subscription. It uses purchased Wallet funds, settled from the provider's reported cost plus a 5.5% funding fee, applied once per request, with no other markup; the card processing fee is shown separately at checkout. While automatic reloads are enabled, a purchased balance below $5 triggers a $20 reload. +Ace has no monthly subscription. It uses purchased funds or valid promotional credits. Usage is calculated for the route that serves each request. Direct provider routes add no funding or service fee. OpenRouter routes include its funding fee (5.5% by default) once, already included in displayed Wallet rates; the card processing fee is shown separately at checkout. Auto reload requires separate consent and a saved card: a fixed $20 is added below $5 of purchased funds, plus the disclosed processing fee. You can configure the monthly automatic-charge limit, not the reload amount or trigger. ## Does switching to my own key turn off Ace reloads? @@ -55,6 +55,14 @@ No. Ultra allows broader investigation and can use more resources. Choose it whe Check it against the original source and saved analysis. Ask OpenScience to distinguish observations, source claims, and interpretation, and to retain uncertainties and failed checks. +## How do I export usage? + +Open **Customize → Usage**, choose a source, date range, and model, then select **Export CSV**. See [Usage reports](/openscience/usage) for the distinction between Wallet charges and estimates. + +## Does a local model keep everything on my device? + +Only the model inference is local. Online tools, remote compute, and signed-in trace sharing can still send data off the device. Review [Privacy and data](/openscience/privacy). + ## Where should I report a problem? Use [Troubleshooting](/openscience/troubleshooting) first, then file a reproducible product issue on GitHub. Use your account's support options for private billing questions. diff --git a/src/content/openscience/files.mdx b/src/content/openscience/files.mdx index 83d303d..63b13ae 100644 --- a/src/content/openscience/files.mdx +++ b/src/content/openscience/files.mdx @@ -5,7 +5,13 @@ description: "Keep inputs, working files, and final results organized and recove Open **Files** in a project to browse its documents and the current conversation's working files. OpenScience can read inputs, write analyses, and show previews of supported formats. A file the agent links in the conversation, whether it lives in the project, in the conversation's working area, or in a connected folder, opens in this pane. -The **Working files** list under **More** shows the folders you connected or approved for this project. The project's own folders, the directories of loaded skills, and folders approved in other projects are not listed there. +Folders connected during project creation are visible immediately. You can browse, edit, rename, and move files to recoverable Trash before sending a message. **More → Add folder** connects another location; **More → Manage workspace folders** opens **Customize → Workspaces**, where you can change access levels and the project's default working folder. + +Files opens on the folder this conversation works in — the one the composer names next to the message box — or on whichever location you left it on. Changing that folder there, including to the conversation's scratch space, moves where Files opens with it. Connected folders have their own tabs beside **Project files**; past three, the rest stay in the **More** menu with remote storage and **Trash**. + +The **Working files** list under **More** shows the folders you connected or approved for this project, plus the folder this conversation works in when that one came from elsewhere: a folder approved for every project, or the folder a conversation inherits from the one that delegated it. The project's own folders, the directories of loaded skills, and folders approved in other projects that this conversation does not work in are not listed there. + +To end a folder's access, open **More** and choose **Revoke** on its row. The confirmation names the folder, the access it removes, and how far ending it reaches: this session, this project, or every project — the scope **Customize → Permissions** shows for the same folder. A folder inherited from the conversation that delegated this one has no **Revoke**: it is browsed here, and ended where it was granted. Revoking drops the grant everywhere it applied and stops any kernel that had the folder mounted; the folder and its files are left untouched, and Files moves to another location. **Customize → Permissions** lists the same connected folders with the same action. ## Organize a project @@ -33,11 +39,13 @@ and plots in results/, and explain every exclusion in results/methods.md. ### Working folder -When the project has a connected read/write folder, a conversation works in it: relative paths the agent writes land in your folder and stay when the conversation ends, while downloads, caches, and throwaway intermediates keep going to scratch. With several connected folders the newest one is used. The composer shows the current choice as a folder chip beside **Tools**; open it to pick another connected folder or **Scratch** for a one-off task that should leave your folders alone. The choice is per conversation, and a folder you disconnect falls back to scratch, never to another folder. +When the project has a connected read/write folder, a conversation works in it: relative paths land in your folder and stay when the conversation ends. Related scripts, analyses, tables, and deliverables stay there; scratch holds disposable caches and intermediates. Use **Customize → Workspaces** to choose a default. **Automatic** uses the newest connected writable folder. The composer shows the current choice beside **Tools**; open it to pick another folder or **Scratch** for a one-off task. You can choose before the first message or switch an existing conversation. Read-only folders are inputs, never a working directory. A task clearly unrelated to a nonempty working folder uses scratch unless you explicitly request a location; an empty working folder can be used for new work. + +The folder chip changes only after the server accepts your selection. If saving fails, the menu keeps the error visible so you can retry. Research work should reuse the selected folder's layout. A separately requested source checkout or experiment directory may still be created inside it. Check the location shown in the preview. To open a known final copy, use **Files → Project files**. Ask OpenScience to save final deliverables there and confirm the exact path in its response. -An older chat link may not identify the intended copy clearly. Use the file browser when the filename is ambiguous. +Conversation links can use a full path or a relative path into a connected folder. Shortened filenames and nested paths are also looked up in the conversation's authorized folders, including Git-ignored output folders. An older chat link may not identify the intended copy clearly; use the file browser or an exact path when the filename is ambiguous. **Session outputs** uses the exact paths recorded by tools and checks that the files remain available to the current conversation. An absolute path identifies @@ -46,6 +54,11 @@ with the same name. ## Edit a supported text file +Completed file edits, writes, and patches show green `+` and red `-` line counts in the activity trace. +Grouped activity adds those operation counts; the file summary below the response shows the net changes +for the turn. Expand a row to inspect its details. Older activity without recorded counts leaves them +blank. WebFetch reads BibTeX and RIS citation exports inline; request a download explicitly to save them. + Use **Source** when the preview offers it. Edit the document, choose **Save file**, and check the saved content. **Discard** abandons the current unsaved edit. Some chat-linked previews are read-only; open the intended project file through Files when you need an editable copy. After saving, choose **Save as Result** to retain a completed output. See [Saved Results](/openscience/results) for the distinction between a working file and a retained deliverable. diff --git a/src/content/openscience/genomics.mdx b/src/content/openscience/genomics.mdx index 89c8c1c..08c5dc6 100644 --- a/src/content/openscience/genomics.mdx +++ b/src/content/openscience/genomics.mdx @@ -47,7 +47,7 @@ An existing embedding is an analysis output, not evidence that the preprocessing ## Choose skills and tools -Search the [skill directory](/openscience/skill-library) for the organism, assay, or method. Check [Tools](/openscience/tool-catalog) for readiness and prerequisites before asking for a pipeline. Biopython has a supported setup path; other specialized packages may require a separate reviewed environment. +Search the [skill directory](/openscience/skill-library) for the organism, assay, or method. Check [Tools](/openscience/tool-catalog) for readiness and prerequisites before asking for a pipeline. Biopython has a supported setup path; other specialized packages may require a separate reviewed environment. With an NVIDIA API key connected, Evo 2 (the BioNeMo genomic foundation model NIM) is available through the scientific-capability tool for sequence generation and scoring. Larger workloads can use [compute jobs](/openscience/jobs). Begin with a pilot, preserve commands and versions, and retrieve the full output set. diff --git a/src/content/openscience/image-generation.mdx b/src/content/openscience/image-generation.mdx index 7195e4a..1a38bed 100644 --- a/src/content/openscience/image-generation.mdx +++ b/src/content/openscience/image-generation.mdx @@ -3,13 +3,21 @@ title: "Generate and edit images" description: "Create illustrations and revise existing images while keeping the outputs in your project." --- -OpenScience includes an image-generation tool for illustrations and edits when compatible image access is configured. Ask for a clear visual and an output path, then inspect the saved image before using it. +OpenScience renders schematics, illustrations, graphical abstracts and image edits with its `generate_image` tool, and saves the result into your project. Ask for a clear visual and an output path, then inspect the saved image before using it. -## Check image access +## Image routes -Image generation requires supported image-capable access. Selecting a text-only or local chat model does not by itself provide image generation. Ask OpenScience to check availability and follow the supported connection guidance it reports. +Image generation runs on one of three routes: -Image-service usage can have separate costs and terms. Verify access before planning a workflow around generated images. +| Route | Model | Notes | +| ----------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- | +| **Ace** | Nano Banana Pro (`gemini-3-pro-image`) | Billed to your Wallet like any other Ace request. One reference image per request. | +| **Your Gemini key** | Nano Banana Pro (`gemini-3-pro-image`) | Connected in Customize → Models. Up to 14 reference images. | +| **Your OpenAI key** | GPT Image 2 (`gpt-image-2`) | Connected in Customize → Models. Reference images are sent as an edit. | + +A personal OpenRouter key does not render images; connect the provider directly, or use Ace. Selecting a text-only or local chat model does not by itself provide image generation. The agent knows which route is active and says so when none is: it will not draw a diagram by hand with TikZ or SVG in its place. + +Image-service usage has its own costs and terms. Verify the route before planning a workflow around generated images. ## Generate a new illustration @@ -20,9 +28,11 @@ labels, a white background, and colorblind-friendly accents. Save it as results/study-workflow.png. This is a conceptual diagram, not measured data. ``` -Specify composition, intended audience, labels, colors, background, and aspect ratio. Supported requested ratios include 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, and 9:16. Actual service support still determines the final output. +Specify composition, intended audience, labels, colors, background, and aspect ratio. Supported ratios are 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16 and 21:9; ask for `2K` when the figure will be printed. -Use a `.png` destination for the most straightforward compatible output. Ask for the exact saved path and open it in Files. +Use a `.png` destination for the most straightforward compatible output (Ace and OpenAI also write `.jpg` and `.webp`). Ask for the exact saved path and open it in Files. + +Method, pipeline and architecture diagrams go through the [schematics skill](/openscience/skill-library). It describes the diagram component by component from your text, renders it with `purpose: "schematic"` (the tool prepends the publication framing adapted from K-Dense's scientific-schematics skill: white background, one sans-serif face, a colorblind-safe palette with one accent, one reading direction, your labels verbatim, nothing invented, no figure numbers inside the image), scores the render on five criteria against the threshold for the document type (a journal figure needs 8.5 of 10, slides 6.5), re-renders once from the critique when it falls short, and finishes at 2K. Conceptual figures and graphical abstracts use `purpose: "illustration"`; edits of an existing image use `purpose: "edit"`. ## Edit an existing image @@ -32,10 +42,12 @@ background to white, and keep the four stages and their order. Save a new file at figures/workflow-revised.png so the draft remains available. ``` -Provide an existing PNG, JPEG, WebP, or GIF image as the input. State what must remain and what should change. The tool edits one supplied image reference; do not assume an unspecified collection of files has been included. +Provide an existing PNG, JPEG, WebP, or GIF image as the input. State what must remain and what should change. Style references (earlier figures, a published diagram) can ride along on a Gemini or OpenAI key; Ace takes one image per request. ## Review the result +Click the thumbnail or **Open image** on a generated-image card to view the original attachment. It remains available if the workspace file is later renamed, edited, or removed. Use **Files** to inspect the current version on disk. Images too large to attach open from their saved path instead. + Check text spelling, labels, arrows, order, visual consistency, and whether a requested edit changed other details. Ask for a specific correction using the saved image as the next input. For a scientific concept, verify that the illustration reflects the intended mechanism and does not imply unsupported evidence. Keep any required attribution or disclosure with the final material. diff --git a/src/content/openscience/index.mdx b/src/content/openscience/index.mdx index 197a11f..5ed2ec8 100644 --- a/src/content/openscience/index.mdx +++ b/src/content/openscience/index.mdx @@ -3,8 +3,6 @@ title: "OpenScience" description: "A workbench for literature, data, code, experiments, and scientific writing." --- - - OpenScience helps you work through a research question in one project. Ask it to compare papers, analyze a dataset, write and run code, or prepare a report with the evidence behind its conclusions. Review its work in the desktop app, browser workspace, or terminal. Choose **Ace** for managed models and research search, connect **your own provider account or API key**, or run a **local model**. You can change model access without starting a new project. @@ -18,6 +16,8 @@ Choose **Ace** for managed models and research search, connect **your own provid +Complete [account setup](/openscience/account) on first launch, then choose the model access that fits your work. Review [Privacy and data](/openscience/privacy) and use [Usage reports](/openscience/usage) to understand what is stored, shared, and billed. + ## Start with a question A useful first request names the input, the output, and any limits: @@ -39,7 +39,7 @@ OpenScience can inspect the files, suggest a method, run the analysis, and save | Terminal | Run `openscience run "your request"` for a single turn. | ```bash -npm install -g @synsci/openscience +npm install -g @synsci/openscience@latest openscience ``` diff --git a/src/content/openscience/installation.mdx b/src/content/openscience/installation.mdx index 1ff1a21..ce6be14 100644 --- a/src/content/openscience/installation.mdx +++ b/src/content/openscience/installation.mdx @@ -6,6 +6,9 @@ description: "Install the desktop app or CLI, check your version, and keep your ## Desktop app Open the [download page](https://openscience.sh/download) and choose your operating system and processor. +The main download button suggests a build for your computer. The macOS, Windows, +and Linux sections below it list all available desktop builds; check the processor +label before downloading. Terminal install commands follow the desktop downloads. | Platform | Download | | --- | --- | @@ -36,7 +39,7 @@ your first task. With Node.js and npm installed: ```bash -npm install -g @synsci/openscience +npm install -g @synsci/openscience@latest openscience --version openscience ``` @@ -57,13 +60,15 @@ Open a new terminal if `openscience` is not found after installation. The standa For Linux compatibility requirements and platform-specific CLI archives, check the release notes. Choose the build that matches your architecture and distribution. -On macOS or Linux, you can also install the standalone CLI through the official -[Homebrew tap](https://github.com/synthetic-sciences/homebrew-tap): +## Desktop app and the command line -```bash -brew install synthetic-sciences/tap/openscience -openscience --version -``` +The app and `openscience` in a terminal are two doors into the same workspace, and they work side by side. + +The app carries its own copy of the command-line app inside the application bundle and updates it with the app. When the `openscience` on your PATH is that copy — `ls -l $(which openscience)` points into `OpenScience.app` or a `resources/sidecar` folder — `openscience upgrade` says so and sends you to **Customize → General → Check for updates**, instead of installing over the app's files. Install the CLI through npm or the standalone installer above if you would rather update it from a terminal. + +To use that copy from a terminal, open **Customize → General → Command line tool** and choose **Install**. The app links `~/.openscience/bin/openscience` to its own copy and adds that folder to your shell's startup file (`~/.zshrc`, `~/.bashrc`, or fish's `config.fish`) the same way the standalone installer does; open a new terminal afterwards. If your shell has no startup file yet, as on a new macOS account, the app creates one: `~/.zshrc` for zsh, `~/.bash_profile` for bash on macOS (`~/.bashrc` elsewhere), or `~/.config/fish/config.fish` for fish. The row says whether the tool is installed and on your PATH, and shows the line to add when no startup file could take it, such as one that is read-only. Each time the app launches it re-points its own link if the app was moved or reinstalled; it never creates a link you did not ask for and never replaces an `openscience` it did not create. `openscience uninstall` run from that link removes the link and the PATH line again; a startup file the app created stays, without the line. The Linux AppImage runs from a temporary mount and cannot be linked, so use the standalone installer on Linux; on Windows, install the CLI separately. + +While the app is running, `openscience` and `openscience web` open a browser tab on the server the app already started, with the same sessions and files, rather than starting a second one. Quit the app and the same command starts a server of its own. ## Verify the installation @@ -79,6 +84,8 @@ openscience models Use the update controls in **Customize → General**. Follow the app's restart prompt when an update is ready. If an in-app update is unavailable on your platform, install the current desktop download. +On macOS, subsequent updates can reuse unchanged parts of the last verified download. Click **Download** as usual; verification and restart work the same way. The first update, or an update without a usable cache, downloads the full app automatically. OpenScience keeps one update archive locally and replaces it as new updates are verified. + For the CLI: ```bash @@ -91,7 +98,7 @@ Or update an npm installation through npm: npm install -g @synsci/openscience@latest ``` -For a Homebrew installation, use `brew update` followed by `brew upgrade openscience`. +A CLI that came with the desktop app is updated by the app; see [Desktop app and the command line](#desktop-app-and-the-command-line). Check `openscience --version` after updating and reopen the workspace. Read the [changelog](https://github.com/synthetic-sciences/openscience/blob/main/CHANGELOG.md) for behavior changes. @@ -106,4 +113,6 @@ openscience uninstall The CLI keeps your work and settings by default. `--purge` also deletes OpenScience configuration and user data; export important sessions and back up project files before choosing it. +Run from the desktop app's copy, `openscience uninstall` removes the command-line link and the PATH line but leaves the app itself, and says so. To finish, move `OpenScience.app` to the Trash on macOS, remove OpenScience from **Add or remove programs** on Windows, or delete the AppImage on Linux. + See [Files and storage](/openscience/files) for export and backup guidance, and [Troubleshooting](/openscience/troubleshooting) if installation or startup fails. diff --git a/src/content/openscience/keyboard-shortcuts.mdx b/src/content/openscience/keyboard-shortcuts.mdx index 0e6a5d4..f97c5db 100644 --- a/src/content/openscience/keyboard-shortcuts.mdx +++ b/src/content/openscience/keyboard-shortcuts.mdx @@ -21,11 +21,13 @@ Keyboard shortcuts can depend on the current page, focus, and active dialog. If | Key | Action | | --- | --- | -| Enter | Send the message when the composer is ready. | +| Enter | Send the message. While a response is running, the message joins the current turn and is answered by it. | | Shift+Enter | Insert a new line. | | / | Search available skills and commands. | | @ | Open available context references in the composer. | -| Escape | Dismiss the active dialog or picker. | +| Escape | Dismiss the active dialog or picker; with none open, stop the running response. | + +The send button becomes **Stop** while a response runs; Enter never stops a response. Use filenames and explicit output paths in the message after adding context. Selecting an attachment or skill does not by itself define the research task. diff --git a/src/content/openscience/literature-review.mdx b/src/content/openscience/literature-review.mdx index cff4456..5b624bc 100644 --- a/src/content/openscience/literature-review.mdx +++ b/src/content/openscience/literature-review.mdx @@ -30,6 +30,21 @@ Available literature databases include PubMed, Europe PMC, arXiv, bioRxiv/medRxi Search access and full-text access are different. A title or abstract result does not mean the full paper was read. Ask OpenScience to identify abstract-only evidence and inaccessible sources explicitly. +## How papers are found and read + +The `literature` tool is the agent's default path to papers. + +- **Search** runs one query against OpenAlex and arXiv together, merges records that describe the same paper (by DOI, arXiv id, or title), and ranks papers both sources agree on first. Each candidate carries the DOI or arXiv id, venue, citation count, abstract, landing page, and whether an open full text exists. The result says which source answered, which answered through a fallback, and which failed. Other connectors (`pubmed`, `europepmc`, `biorxiv`, `crossref`, `semantic-scholar`) can be named with `sources`. +- **Read** takes a DOI, arXiv id, URL, local PDF, or exact title, resolves the open full text (arXiv PDFs directly, publisher and repository copies through OpenAlex's open-access locations), downloads it once into the session's paper cache, and extracts page-addressed text with `pdftotext` (poppler) or PyMuPDF. The agent reads the opening pages, a page range, or the passages matching a phrase, each tagged with its page number. When only the abstract is open, the result says so instead of pretending to have read the paper. + +The cache lives in the session's scratch workspace under `papers/`, so re-reading a paper costs nothing and survives across turns. + +### When arXiv rate limits + +arXiv's API answers bursts of requests with `429` for a while, often after a long stall. OpenScience now treats one such answer as a signal: the API is held for a cooldown (a minute, doubling on repeats) and arXiv records are served from OpenAlex, which indexes every arXiv paper under `10.48550/arXiv.`, or from the paper's own `arxiv.org/abs` page. Results obtained this way are marked `via`. If every route fails, the error reports the HTTP status, the endpoint, the number of attempts, and any requested wait, together with the concrete alternatives, so the agent can choose a different source instead of retrying the same call. + +Text extraction needs `pdftotext` (macOS: `brew install poppler`; Debian and Ubuntu: `apt-get install poppler-utils`) or the `pymupdf` Python package. Without either, the PDF is still downloaded and the agent can open it with the `read` tool. + ## Compare findings ```text diff --git a/src/content/openscience/models.mdx b/src/content/openscience/models.mdx index d9d5e6d..cb1fb18 100644 --- a/src/content/openscience/models.mdx +++ b/src/content/openscience/models.mdx @@ -11,11 +11,11 @@ Open **Customize → Models** to choose model access and manage your connections | Keys & subscriptions | Connect a provider API key or supported sign-in. | Existing provider accounts and subscriptions. | | Local model | Add a running endpoint in **Customize → Local models**. | Models on your machine or infrastructure you manage. | -See [Pricing](/openscience/pricing) before starting paid work. A model's presence in a public catalog does not guarantee that your account can use it. +First-run setup requires an [account](/openscience/account); choosing your own provider keeps model requests on that provider's connection. See [Pricing](/openscience/pricing) before starting paid work. A model's presence in a public catalog does not guarantee that your account can use it. ## Use Ace -Select **Ace** in **Customize → Models**. Sign in when prompted, check the funding workspace, then add purchased Wallet funds or authorize automatic reloads. Select an available model and return to your conversation. +Select **Ace** in **Customize → Models**. Sign in when prompted, check the funding workspace, then confirm purchased or valid promotional credits. Add funds if needed; automatic reload is optional and requires separate consent. Select an available model and return to your conversation. The Wallet control opens account and funding details. Changing model access to **Keys & subscriptions** does not cancel automatic reloads; manage them in Wallet. See [Ace and your account](/openscience/ace). @@ -52,6 +52,8 @@ openscience keys signin Complete the browser sign-in and select an available model. Access and limits depend on your provider account. Signing into a provider does not add funds to Ace. +ChatGPT access tokens renew automatically while work continues. Disconnecting or replacing a provider connection still stops work using the previous credentials. + To disconnect that connection: ```bash @@ -60,7 +62,9 @@ openscience disconnect codex ## Select a model -Use the conversation's model picker. For a terminal run, copy an exact identifier from `openscience models --flat`: +Use the conversation's model picker. Each row leads with what a request on that model is charged to: **Wallet**, **Your key**, **Subscription**, or **Local**. When a model is available through more than one connection, the row names the one that choosing it selects: the credential you are already using stays in use, then your configured default, then the **Model access** mode. A connection the app cannot classify, such as a cloud profile, has no label. + +For a terminal run, copy an exact identifier from `openscience models --flat`: ```bash openscience models --flat @@ -81,22 +85,26 @@ Replace the example value with your configured model. See [Configuration](/opens ## Reasoning, context, and rates -Use the effort control beside the model name in the composer to choose the model's supported effort, Fast mode, and context window. Available choices depend on the exact model and access route; there is no universal list. View current prices in **Customize → Models → Rates and limits**. +Use the effort control beside the model name in the composer to choose the model's supported effort, Fast mode, and context window. Available choices depend on the exact model and access route; there is no universal list. View current prices in **Customize → Models → Rates and limits**. Ace shows Wallet input/output rates per million tokens in both places, including Fast and long-context tiers. Variable prices say **Up to** for input and output; their cache prices are estimates. Fixed schedules show exact rates. Provider-key connections show catalog estimates billed by your provider. Verified effort choices remain usable while Ace refreshes pricing. Fast appears only after its route and prices are verified. If the options report that rates are unavailable, choose **Refresh options**; this only reloads metadata and does not send a model request, change your selection, or purchase anything. +Open the context indicator for the latest request's token breakdown and the session's recorded model cost. The header and details include the lead's cost and completed direct worker costs, and display small charges below one cent. Recorded Ace turns stay labeled **Ace** if you later switch to provider keys. + +The token breakdown separates ordinary input, cache reads, cache writes, and output when reported by the model service. Cache writes are counted once in the total. A reported request charge takes precedence over an estimate from the token rates. Ace applies the same rounding to each reported request charge as Wallet settlement; provider-key costs retain the provider's reported precision. + ### GPT-6 Astra and Claude Fable 5.1 Both models offer **Low, Medium, High, Extra high, and Max** effort. Their transport contracts remain distinct: -- **GPT-6 Astra:** native OpenAI access uses Responses for tool calls. The public API supports a 1.05M context window; supported ChatGPT access has separate 272K/872K context choices. OpenRouter uses its documented normalized tool interface. Native API and subscription Fast are not enabled merely because Ace's OpenRouter route supports priority. +- **GPT-6 Astra:** native OpenAI access uses Responses for tool calls. The public API supports a 1.05M context window; supported ChatGPT access has separate 272K/872K context choices. Ace uses Azure Responses behind its compatible managed gateway. Ace Fast uses OpenAI's own priority processing alongside Azure Global Standard. Direct OpenRouter connections retain their own supported options. - **Claude Fable 5.1:** adaptive thinking is always on, with High as the default; there is no Off or manual thinking-budget option. Native Anthropic access preserves valid thinking blocks and uses the documented handling for blocks invalidated by a changed conversation prefix. Forced tool selection is unsupported. Fable 5.1 has no Fast mode. Native Fable requests the provider's readable thinking and progress output (`thinking.display: "summarized"`), which the API otherwise omits by default. This is provider-supplied text, not an additional summary generated by OpenScience, and is not the model's private internal reasoning. Model availability still depends on your account and the selected route. The exact IDs are `openai/gpt-6-astra`, `openai-codex/gpt-6-astra`, and `anthropic/claude-fable-5-1` for those native connections. OpenRouter slugs are `openai/gpt-6-astra` and `anthropic/claude-fable-5.1` (prefixed by `openrouter/` in CLI model selections). -Fable 5.1's **Ace route is withheld by default** until its multi-turn thinking-replay compatibility through OpenRouter is verified. Native Anthropic support is available independently. Reviewed prices or a stored key do not establish managed availability; OpenScience requires an explicit approval signal from the Ace catalog before offering that route. The client also leaves Fable 5.1 out of automatic BYOK OpenRouter catalog imports; explicit custom routes remain user-controlled and their replay compatibility is unverified. +Fable 5.1 replaces Fable 5 in Ace and runs through Anthropic's API behind the managed gateway. OpenScience offers it when the Ace catalog confirms that route is available, preserving its bound thinking replay across tool turns. Native Anthropic support is available independently. The client still leaves Fable 5.1 out of automatic BYOK OpenRouter catalog imports; explicit custom routes remain user-controlled and their replay compatibility is unverified. Provider contracts: [Astra](https://developers.openai.com/api/docs/models/gpt-6-astra), [OpenRouter Astra](https://openrouter.ai/openai/gpt-6-astra), and [Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview). @@ -110,6 +118,8 @@ Readable passages appear as plain prose, with routine provider phase headings re An open response can pause between outputs. OpenScience shows the time since the last output and keeps waiting by default; **Stop** cancels your wait without undoing completed work. Explicit provider timeout settings still apply, as do provider-side limits. Resubmitting a stopped or failed request can incur a new charge. +For usage across conversations, open **Customize → Usage**. See [Usage reports and CSV exports](/openscience/usage). + ## Local and custom endpoints Use [Local models](/openscience/local-models) for Ollama, LM Studio, and self-hosted endpoints. For a service not listed in the connection picker, see [Custom providers](/openscience/custom-providers). diff --git a/src/content/openscience/molecular-research.mdx b/src/content/openscience/molecular-research.mdx index 8df188e..4924f25 100644 --- a/src/content/openscience/molecular-research.mdx +++ b/src/content/openscience/molecular-research.mdx @@ -41,7 +41,7 @@ Structure prediction, docking, sequence design, and simulation require different ## Use connected scientific tools -The catalog includes connected prediction and design tools where supported. Configure the required personal service access, inspect readiness, and start with a small documented input. Ask for the accepted parameters, expected output files, and cost before a larger task. +The catalog includes connected prediction and design tools where supported. With your NVIDIA API key connected, the NVIDIA BioNeMo NIMs are available through the scientific-capability tool: Boltz-2 and OpenFold2/OpenFold3 for structure prediction, MSA Search for alignments, DiffDock for docking, GenMol and MolMIM for molecule generation, and RFdiffusion with ProteinMPNN for binder design; the `protein-binder-design` skill chains them the way the [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit) does. Configure the required personal service access, inspect readiness, and start with a small documented input. Ask for the accepted parameters, expected output files, and cost before a larger task. Keep predictions, scoring functions, confidence measures, and experimental measurements distinct. A plausible-looking structure or pose is not experimental validation. diff --git a/src/content/openscience/permissions.mdx b/src/content/openscience/permissions.mdx index 657a1a4..52664cb 100644 --- a/src/content/openscience/permissions.mdx +++ b/src/content/openscience/permissions.mdx @@ -11,16 +11,22 @@ OpenScience can edit files, run commands, and use connected services. Choose the | --- | --- | | Ask always | Review actions that change files, use the network, run compute, or incur provider costs. | | Ask risky | Let routine reversible work proceed and review external, costly, or hard-to-reverse actions. | -| Full access | Run without routine prompts, subject to provider and system restrictions. | +| Full access | Run without routine prompts; paid compute asks once per time allowance. | An organization's policy may restrict the modes available. Use the more interactive option while learning a new project or reviewing unfamiliar inputs. The mode belongs to the project you set it in. Switching to a wider mode also settles prompts that are already waiting, so cards raised under **Ask risky** disappear once **Full access** covers them. +In **Ask risky**, research searches and WebFetch reads from enabled Network groups or custom allowed domains proceed without another tool approval, including in delegated workers. The literature group includes arXiv, ACL Anthology, OpenReview, and major conference archives. A new destination or redirect outside that list still asks for network approval. **Ask always** still asks, and explicit tool rules remain effective in every mode. Local and private network addresses remain blocked by the retrieval broker. + +**Independence** controls how the agent handles decisions and questions. **Tools → Action approval** controls execution permissions; choosing Independent does not change that permission mode. + ## Approval scopes Each request card offers **Allow once**, or **Allow** with a scope: **This conversation**, **This project**, and for network hosts and searches **Allow always** across the installation. Folder access has no installation-wide scope: a folder approved while working in one project is never reachable from another project, and the request card names the exact folder being granted. +Paid compute is bounded by time rather than bound to one job. A Modal job card offers **Allow once** for that exact plan, or **Allow** for this conversation or this project together with a time allowance (four times the job's timeout, rounded to whole hours, between one and eight). Under an allowance, later Modal jobs in that scope run without a card while the sum of their timeouts fits; the card returns when a job would exceed what is left. A study's approval carries an allowance equal to its hour budget for the jobs that follow its runs, such as the final refit and an external baseline. **Full access** does not remove this card; it asks once per allowance. Full access does run package installs and other environment changes in the Python and R kernels without a card, as it already does for the same commands in the shell; **Ask risky** still asks for each exact change. **Customize → Permissions** lists every standing approval by what it covers, with a Revoke action. + ## Network commands and publishing The sandbox denies network access to shell commands. A command that needs it, such as `git push`, `gh`, `hf upload`, a package install, or `curl`, asks once for its destination host; approving it runs that command with the network and the same file confinement. Approve for **This project** or **Allow always** to stop asking for a host you publish to regularly, and Full access approves automatically. diff --git a/src/content/openscience/planning.mdx b/src/content/openscience/planning.mdx index 5a2a395..b0c7175 100644 --- a/src/content/openscience/planning.mdx +++ b/src/content/openscience/planning.mdx @@ -35,7 +35,7 @@ Plan mode can inspect material and prepare its plan. Review the assumptions, dep a successful rerun from the preserved inputs. ``` -Use `/status` to inspect current progress. Keep the task's acceptance criteria in a project file when the goal is long enough to span compaction or handoff. +The plan panel and session header show current progress. Keep the task's acceptance criteria in a project file when the goal is long enough to span compaction or handoff. Persistent goals still require the application and necessary resources to be running. They do not schedule future work while the machine is off. diff --git a/src/content/openscience/preferences.mdx b/src/content/openscience/preferences.mdx index dfa438c..0ee7633 100644 --- a/src/content/openscience/preferences.mdx +++ b/src/content/openscience/preferences.mdx @@ -30,12 +30,20 @@ Context compaction is automatic; there is no percentage selector in General. See Check the account and funding workspace before paid work. [Ace](/openscience/ace) explains account connection, Wallet access, and switching workspaces. +## Usage and privacy + +Open **Customize → Usage** for date-filtered activity and CSV exports. Managed Wallet charges and device-local provider activity have different scopes; see [Usage reports](/openscience/usage). + +Under **General → Data & privacy**, review **Share session traces** and delivery status. Local models and personal keys do not disable trace sharing automatically. See [Privacy and data](/openscience/privacy). + ## Reasoning visibility Use **Show reasoning and activity / Hide reasoning and activity** above a turn to expand or collapse its steps. Each turn remembers its own choice; changing one does not move or hide the history in other turns. New live turns open automatically and stay open when they finish; a turn you explicitly collapse stays collapsed. Answers, scientific results, pending approvals/questions, and failed tool calls remain visible when steps are collapsed. There is no separate global reasoning toggle or Detailed/Compact mode. Readable provider text is shown inline, with routine action headings omitted. Providers may supply summaries or no readable reasoning; OpenScience cannot reveal private reasoning the provider did not send. +Consecutive reasoning fragments appear in one expandable row. Completed reads, searches, and edits stay grouped while a long task runs; expand a group to inspect each original tool result. Failures and pending requests remain separate. Patch summaries count the files reported by the tool. + ## Updates and release notes Use the update controls available for your installed interface. The desktop app and CLI have different update entrypoints; see [Installation and updates](/openscience/installation). diff --git a/src/content/openscience/pricing.mdx b/src/content/openscience/pricing.mdx index d4f912a..49587e8 100644 --- a/src/content/openscience/pricing.mdx +++ b/src/content/openscience/pricing.mdx @@ -3,14 +3,14 @@ title: "Pricing and usage" description: "What the workbench costs, how Ace uses your Wallet, and how to control spending." --- -The OpenScience workbench is free and open source. Choose how to pay for the models and services you use: +The OpenScience workbench is free and open source. First-run setup requires a Synthetic Sciences account; Ace is optional. Choose how to pay for the models and services you use: | Model access | OpenScience account | How usage is paid | | --- | --- | --- | -| Ace | Required | Pay as you go from the selected workspace's purchased Wallet. | -| Your API key | Optional | Billed by your provider under its own rates. | -| Supported provider sign-in | Optional | Subject to that provider account's access, limits, and terms. | -| Local model | Optional | Runs on your hardware without an Ace model charge. | +| Ace | Required | Pay as you go from the selected workspace's purchased funds or valid promotional credits. | +| Your API key | Required for first-run setup | Billed by your provider under its own rates. | +| Supported provider sign-in | Required for first-run setup | Subject to that provider account's access, limits, and terms. | +| Local model | Required for first-run setup | Runs on your hardware without an Ace model charge. | Using your own key, provider sign-in, or local model does not charge your Ace Wallet for model usage. Separately requested managed search or other paid services can still have costs. @@ -20,24 +20,26 @@ Ace gives you access to managed models and research search without setting up in | Item | Amount | | --- | --- | -| Enable Ace | $0 authorization | +| Enable Ace access | $0; does not authorize automatic card charges | | Monthly subscription | None | | Usage | Pay as you go | -| Usage rate | Provider's reported cost plus a 5.5% funding fee, applied once per request; no other markup | -| Automatic Wallet reload | $20 when the purchased balance drops below $5, while Ace reloads are enabled | +| Usage rate | The displayed Wallet rates for the selected model and speed; direct routes add no fee | +| Optional automatic Wallet reload | Fixed $20 when purchased funds fall below $5, with separate consent and a saved card | | Card processing fee | Shown separately at checkout | -A reload adds **$20 to your purchased Wallet balance**. The $20 is a funding amount, not a monthly plan or a promise of unlimited usage. Usage is settled from the provider's reported cost plus a 5.5% funding fee, applied once per request, with no other markup; the card processing fee is shown separately at checkout. Review the current terms in [your billing account](https://app.syntheticsciences.ai/billing) before authorizing payment. +A reload adds **$20 to your purchased Wallet balance**. The $20 is a funding amount, not a monthly plan or a promise of unlimited usage. Usage is calculated for the route that serves each request. Direct provider routes add no funding or service fee. OpenRouter routes include its funding fee (5.5% by default) once, already included in displayed Wallet rates; the card processing fee is shown separately at checkout. Review the current terms in [your billing account](https://app.syntheticsciences.ai/billing) before authorizing payment. -You can use purchased Wallet funds for available managed models without leaving automatic reloads enabled. Availability depends on the account and its current balance. +Purchased funds and valid promotional credits can fund available managed models without automatic reloads or a saved card. Promotional credit is separate from purchased Wallet balance and may expire. Access still depends on workspace permissions, sufficient credit, and spending limits. ## Check model rates before a task Open **Customize → Models**, choose a model, and open **Rates and limits**. Prices are shown in USD per million tokens. Input, output, and cached input can have different rates; some models also have higher rates for long requests. +Fixed schedules show exact rates. Variable schedules label input and output **Up to** and cached rates as estimates. Standard and Fast may have different hosting and fee schedules; read the selected speed's disclosure. A rate ceiling is not a guaranteed final request charge. + The context window is how much material a model can handle in one request. A pricing threshold is where a different rate begins. They need not be the same number. -For an illustrative model charging $2 per million input tokens and $10 per million output tokens, 10,000 input tokens and 2,000 output tokens would cost $0.04 at those rates; through Ace, the 5.5% funding fee is added once to that provider cost. This is an example, not an OpenScience model quote. Use the rates displayed for your selected model and the final Wallet entry for actual charges. +For illustrative Wallet rates of $2 per million input tokens and $10 per million output tokens, 10,000 input tokens and 2,000 output tokens cost $0.04. Do not add another fee to displayed Wallet rates. This is an example, not an OpenScience model quote. Use the rates displayed for your selected model and the final Wallet entry for actual charges. Long conversations may send earlier context again. Larger inputs, longer outputs, extra research branches, and external searches can all increase a task's total cost. Selecting a local model removes the model usage charge from Ace; it does not make separately connected services free. @@ -61,16 +63,24 @@ openscience wallet topup `wallet topup` opens billing so you can review and confirm a payment. +## Review and export usage + +Use **Customize → Usage** for date filters, source and model filters, daily activity, and **Export CSV**. Managed usage reports Wallet charges; API-key and subscription reports use saved device activity and do not include your subscription fee. Read [Usage reports and CSV exports](/openscience/usage) for scopes and reconciliation. + ## Control spending Open **Wallet** from **Customize → Models**, or visit [billing](https://app.syntheticsciences.ai/billing), to review funds, set a monthly usage limit, and turn off future reloads. +The monthly managed-usage limit controls spend. The monthly automatic-charge limit controls card reloads, including the disclosed fee. They are independent; the reload amount and trigger remain $20 below $5. Turning off Ace access in the account stops new managed work and reloads while preserving credit, saved cards, and limits. An already submitted payment or reserved request can still settle. + **Switching to Keys & subscriptions does not turn off Ace automatic reloads.** Manage the reload authorization in Wallet. Turning off future reloads does not reverse usage that has already occurred. Start expensive work with a small pilot. State a budget and ask for approval before expanding an experiment. Prompt instructions help scope the task; use account controls for spending limits. ## Pending amounts and final charges +Local session usage uses the gateway's calculated Wallet amount when available; this can appear before the final Wallet entry posts. + A request may temporarily reserve Wallet funds. After usage is confirmed, the final charge is recorded and unused reserved funds are released. A pending amount can reduce the available balance before it becomes a completed charge. If a request fails or times out, review its partial output before retrying: work may already have occurred. Keep the request or operation identifier, time, and selected workspace when asking about an unexpected or pending charge through your account's support options. diff --git a/src/content/openscience/privacy.mdx b/src/content/openscience/privacy.mdx new file mode 100644 index 0000000..79a082b --- /dev/null +++ b/src/content/openscience/privacy.mdx @@ -0,0 +1,43 @@ +--- +title: "Privacy and data" +description: "Understand local storage, model and tool requests, session trace sharing, and deletion controls." +--- + +OpenScience works with local projects, connected model providers, and optional online tools. Which data leaves your device depends on the connections and actions you use, as well as your trace-sharing settings. + +## Know where data goes + +| Surface | Data involved | +| --- | --- | +| Local project and app storage | Working files, saved conversations, scratch data, Results, and settings. | +| Selected model route | The conversation context and attachments sent for inference. Ace uses a managed route; your own connection uses its provider. | +| Search, connectors, and remote compute | Queries, selected inputs, and files required by the specific service or task. | +| Session trace sharing | Diagnostic conversation and tool records uploaded under the account and device privacy settings. | + +Choosing a local model removes the remote model request. It does not disable online tools or signed-in trace sharing. Review both before assuming a task is offline. + +## Review session trace sharing + +While signed in, session traces are shared by default, including sessions using your own keys, subscriptions, and local models. Existing opt-outs remain in effect. Traces can include prompts and model context, provider-visible reasoning and responses, tool inputs and outputs, searches, errors, and reported usage. + +Open **Customize → General → Data & privacy → Share session traces** to turn off uploads from this device and discard queued and rejected records. Account preferences can disable sharing across devices or exclude user-owned routes. The device setting does not override an account opt-out. Signing out also stops uploads. + +The **Delivery** row distinguishes queued, acknowledged, and rejected records. Temporary failures can leave records waiting for retry. Large text may be truncated and binary attachments represented by metadata. Known credentials are redacted, but private research can still appear in prompts and tool output. + +The [privacy policy](https://openscience.sh/privacy) describes retention and account deletion controls. Disabling future uploads and deleting already stored account data are different actions. Review the scope of the deletion control before confirming it; telemetry deletion does not remove your local project, revoke external credentials, or reverse billing records. + +## Control file and tool access + +Connect only the folders needed for the project. Read approval requests before granting broader filesystem access, running code, publishing, or sending data to a service. See [Permissions](/openscience/permissions), [Projects](/openscience/projects), and [Connectors](/openscience/connectors). + +Instructions can guide how the agent handles data, but they are not a substitute for folder permissions or service access controls. Retrieved papers, pages, and tool output are evidence to inspect, not authority to disclose unrelated files or secrets. + +## Handle keys and exports + +Keep secrets in connection settings, supported environment variables, or your secret manager. Do not place them in prompts, project instructions, example files, or shared repositories. Removing a local connection does not revoke the key at its provider. + +Conversation exports and saved Results can contain research material. Inspect them before sharing and include only data the recipient may access. Account sign-in and trace uploads are not full project backups; keep your own copies of inputs, code, and outputs. See [Files and storage](/openscience/files) and [Share and hand off research](/openscience/team-workflows). + +## Report a privacy or security issue + +Use private account support for account data and payment details. Follow the [security reporting policy](https://github.com/synthetic-sciences/openscience/blob/main/SECURITY.md) for vulnerabilities. A public issue should contain a minimal reproduction with credentials and private research removed. diff --git a/src/content/openscience/projects.mdx b/src/content/openscience/projects.mdx index 57d3709..8292f59 100644 --- a/src/content/openscience/projects.mdx +++ b/src/content/openscience/projects.mdx @@ -21,6 +21,19 @@ paths and suggest the first task. Ask before editing original inputs. The source-folder form supports up to ten selected folders. Connected folders are working material, so choose deliberately and keep backups of original inputs. +## Manage workspace folders + +Open **Customize → Workspaces** and select the project. Its folders are available immediately, including before its first conversation. You can also reach these settings from **Files → More → Manage workspace folders**. + +- **Connect folder** adds an existing folder by path or through **Browse**. +- **Read only** lets OpenScience inspect files; **Read & write** also allows edits. +- **Use by default** selects the project's working folder. The composer can override it for one conversation, including choosing temporary **Scratch**. +- **Disconnect** removes this project's access without moving or deleting files. Affected running tools stop so they cannot retain the old access. + +Changes apply to existing and future conversations in that project. A conversation's explicit working-folder choice takes priority. If that chosen folder loses write access, the conversation falls back to scratch rather than silently choosing another folder. + +For related work, OpenScience uses the connected working folder and preserves its existing layout. An empty folder is ready for new work. A task clearly unrelated to the contents of a nonempty folder uses scratch unless you explicitly specify where it should work. + ## Open an existing folder from the CLI ```bash diff --git a/src/content/openscience/python-r.mdx b/src/content/openscience/python-r.mdx index e73abad..b139fc2 100644 --- a/src/content/openscience/python-r.mdx +++ b/src/content/openscience/python-r.mdx @@ -11,6 +11,8 @@ Open **Customize → Compute** and check **Python starter** and **R starter**. F The Python starter includes NumPy, pandas, SciPy, Matplotlib, Seaborn, and Pillow. The R starter includes tidyverse, ggplot2, and jsonlite. Additional scientific packages have separate setup requirements; use [Tools](/openscience/scientific-tools) to check them. +Each starter is checked by importing its packages before it is used. A starter that fails that check is removed rather than kept half-built, and the Compute panel shows the interpreter's own error, such as a package that would not load. The starters run from their own Conda layout without activation: on Windows, OpenScience puts the environment's `Library\bin`, MinGW and `Scripts` directories on `PATH` itself and runs R with `--vanilla` and an empty `R_LIBS_USER`, so another Anaconda or R installation on the machine cannot shadow the starter's libraries. + ```text Check that the Python analysis environment can import pandas and Matplotlib. Read the first rows of data/samples.csv and report its columns diff --git a/src/content/openscience/quickstart.mdx b/src/content/openscience/quickstart.mdx index 9e10b6a..8d51be2 100644 --- a/src/content/openscience/quickstart.mdx +++ b/src/content/openscience/quickstart.mdx @@ -10,7 +10,7 @@ Start with a small dataset or a few papers you know. This makes it easier to che Download the [desktop app](https://openscience.sh/download) for your operating system and open it. You can also install the command-line app with npm: ```bash -npm install -g @synsci/openscience +npm install -g @synsci/openscience@latest openscience ``` @@ -20,7 +20,7 @@ openscience openscience ~/research/my-project ``` -`npx synsci` is an alternative launcher that installs and opens OpenScience. It requires Node.js and npm. +`npx synsci@latest` is an alternative launcher that installs and opens OpenScience. It requires Node.js and npm. ## 2. Set up your account, Ace, and connections @@ -33,13 +33,17 @@ the workspace. Every install sees the setup once. or sign in and choose a workspace you belong to. An account is required; on a machine without a browser, paste a sign-in key instead. 2. **Ace** (recommended, optional). **Turn on Ace** opens your billing page. - Ace is a $0 activation, pay as you go: managed frontier models, literature + Ace access costs $0 to enable, with pay-as-you-go usage and separate consent for automatic reload: managed frontier models, literature search through Firecrawl, scientific schematics and image generation, and one team wallet. OpenScience notices when Ace is on and continues. **Skip for now** keeps your own keys as the model source. 3. **Connect your own models** (optional). Connect a ChatGPT / Codex - subscription, add Anthropic, OpenAI, OpenRouter, or Firecrawl keys, or detect a - Modal compute profile. Keys are stored in an owner-only file on this device. + subscription, add Anthropic, OpenAI, OpenRouter, Google, or Firecrawl keys, or + detect a Modal compute profile. A provider key is checked with its provider + before it is saved: a key the provider refuses is not stored, and a provider + that cannot be reached saves the key and says it could not be checked. A + provider OpenScience already reaches, such as a key in your environment, shows + as connected. Keys are stored in an owner-only file on this device. 4. **Done.** **Open workspace** shows the Projects page. Select **New project**, open a folder or start blank, and send your first message. @@ -55,7 +59,7 @@ Open **Customize → Models** and choose the option that fits your setup: | Your provider | Select **Keys & subscriptions**, then connect an API key or a supported provider sign-in. | Your provider's usage or subscription terms. | | Local model | Open **Customize → Local models**, connect a running endpoint, and select its model. | Your hardware; no Ace model charge. | -An OpenScience account is optional when using your own provider access or local models. See [Models](/openscience/models), [Local models](/openscience/local-models), and [Pricing](/openscience/pricing) for the details. +First-run setup requires a Synthetic Sciences account. Ace remains optional, and your own provider access or local models remain direct after setup. See [Account and workspaces](/openscience/account) for device access and workspace selection. See [Models](/openscience/models), [Local models](/openscience/local-models), and [Pricing](/openscience/pricing) for the details. For terminal setup, run `openscience keys add` to connect a provider, or `openscience local add` to connect a local endpoint. diff --git a/src/content/openscience/remote-compute.mdx b/src/content/openscience/remote-compute.mdx index 73607f5..6718078 100644 --- a/src/content/openscience/remote-compute.mdx +++ b/src/content/openscience/remote-compute.mdx @@ -27,6 +27,8 @@ Use [Compute jobs](/openscience/jobs) for the lifecycle after connection. Defaults can be changed for future work. A saved token alone is not the same as an enabled and tested connection. Begin with a small environment check and confirm that its output returns to the project. +What Modal jobs can ask for: a GPU by Modal's type name (`T4`, `L4`, `A10`, `L40S`, `A100`, `A100-80GB`, `H100`, `H200`, `B200`; `H100:2` for two, up to eight per container, four for A10), up to 24 hours of wall time (the default is 60 minutes), and outbound network only when you enable it; it is off by default. Modal may serve an `A100` request on an 80 GB card and an `H100` request on an H200; `H100!` opts out of the upgrade. OpenScience talks to Modal through its JavaScript SDK and never runs `modal` CLI commands or Python apps of its own. + ## Add an SSH host Supply the fields shown in **Remote hosts**: @@ -61,6 +63,10 @@ The Compute panel includes connections for TensorPool, Lambda, Prime Intellect, These connections do not imply automatic paid instance creation or arbitrary provider commands. If the panel reports credential-only access or a failed connection test, resolve that state before relying on it for a task. +## Large inputs + +Modal jobs stage their inputs from the working directory. Everything a glob or the default sweep picks up must fit 100 MiB together, so an approval never covers bytes that were not listed. A file the request names by its exact path, such as a model checkpoint or a dataset, may be up to 2 GiB (4 GiB for a job in all); the approval card lists it with its size and hash. Name large files in `uploads` rather than compressing them to fit. + ## Keep costs and outputs explicit Ask for a resource estimate, maximum duration, and a pilot before a large run. Use the provider's account limits in addition to instructions in the conversation. After completion, retrieve and inspect outputs, then release resources that are no longer needed. diff --git a/src/content/openscience/scientific-tools.mdx b/src/content/openscience/scientific-tools.mdx index b2627ac..7782d24 100644 --- a/src/content/openscience/scientific-tools.mdx +++ b/src/content/openscience/scientific-tools.mdx @@ -17,7 +17,9 @@ For everyday file operations, search, Python, R, and jobs, use the [built-in too | --- | --- | | Ready | Start with a small, known input. | | Connected | Confirm the account and any service charges before use. | -| Not installed / Setup needed | Follow the setup or connection action. | +| Not installed | Install the packaged local environment; the local tools share it. | +| Setup needed | Connect the service the tool runs on: an NVIDIA key in Credentials, or Modal in Compute. | +| Hosted only | This device has no packaged local environment for the tool. It runs on Modal once Compute is connected. | | Needs attention | Open the reported problem and resolve it before retrying. | | Unavailable | Use another supported tool or resolve the missing prerequisite. | @@ -27,6 +29,8 @@ Availability can differ across machines, operating systems, and accounts. An exp Supported setup paths include common numerical, plotting, machine-learning, sequence-analysis, and cheminformatics tools such as SciPy, Matplotlib, scikit-learn, Biopython, and RDKit. +The packaged local environment is released for Apple silicon Macs and for Linux on x64 and arm64. On Windows and on Intel Macs the same tools are listed under **Connected science** as **Hosted only** and run on Modal instead. A package installed into the project's own Python environment is separate from the packaged tool runtime and does not change the row. + ```text Check whether RDKit is ready. If it is, calculate molecular weights for the SMILES in data/molecules.csv and save the results. Report invalid diff --git a/src/content/openscience/server-hosting.mdx b/src/content/openscience/server-hosting.mdx index 701ae5f..bc3bbd3 100644 --- a/src/content/openscience/server-hosting.mdx +++ b/src/content/openscience/server-hosting.mdx @@ -14,7 +14,7 @@ openscience serve --port 0 --format json Port `0` lets the runtime choose an available local port. The command prints one JSON readiness record containing `type: "server.ready"`, `schemaVersion: 1`, `url`, `pid`, and `version`. Use that URL, then check `GET /global/health`. Without `--format json`, the command keeps its human-readable announcement. -The process remains available until SIGINT, SIGTERM, or its bound desktop parent exits. It closes HTTP/event connections and performs runtime cleanup before exiting. Stopping a server is different from disconnecting an observing client: do not assume an active model loop resumes after the server exits. Inspect detached jobs through their retained job records and reconcile remote state before submitting replacements. +The process remains available until SIGINT, SIGTERM, or its bound desktop parent exits. It closes HTTP/event connections and performs runtime cleanup before exiting, and a stop that completes exits `0` — including one that could not release a runtime, which it reports as a warning on standard error rather than a failure, because a stop you asked for is not a failed unit. Repeating the signal while it drains stops the process immediately instead, with `128` plus the signal number, and a stop that does not finish inside its deadline is cut short and exits `1`. Stopping a server is different from disconnecting an observing client: do not assume an active model loop resumes after the server exits. Inspect detached jobs through their retained job records and reconcile remote state before submitting replacements. ## Connect to a separately managed server diff --git a/src/content/openscience/service-credentials.mdx b/src/content/openscience/service-credentials.mdx index efcfd38..f0ae26f 100644 --- a/src/content/openscience/service-credentials.mdx +++ b/src/content/openscience/service-credentials.mdx @@ -23,8 +23,8 @@ Do not paste secrets into conversation text or project files. A saved credential | Literature access | API key | Supported literature retrieval with your own access. | | Firecrawl | API key | Your own web and research-search access. | | OpenAlex | Contact email, optional API key | Scholarly records with your configured access. | -| NVIDIA API | API key | Supported scientific prediction tools using your account. | -| NVIDIA NGC Registry | NGC API key | Approved container access for supported workflows. | +| NVIDIA API | API key | The ten NVIDIA BioNeMo NIM adapters (Boltz-2, DiffDock, Evo 2, GenMol, MolMIM, MSA Search, OpenFold2, OpenFold3, ProteinMPNN, RFdiffusion) billed to your NVIDIA account; workflows follow the [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). | +| NVIDIA NGC Registry | NGC API key | Approved BioNeMo container access for supported workflows. | | Hugging Face | Access token | Authorized models, datasets, and Hub material. | | Tinker | API key, optional base URL | Compatible training and inference workflows. | | Weights & Biases | API key | Experiment-management workflows you explicitly configure. | diff --git a/src/content/openscience/skill-library.mdx b/src/content/openscience/skill-library.mdx index d81efa4..853bb52 100644 --- a/src/content/openscience/skill-library.mdx +++ b/src/content/openscience/skill-library.mdx @@ -3,7 +3,7 @@ title: "Skill directory" description: "Browse the research procedures included with this documentation version." --- -OpenScience includes 313 skill files in this version. This directory is generated from the bundled library. Each entry describes the procedure and links to its full usage instructions and supporting files on GitHub. +OpenScience includes 367 skill files in this version. This directory is generated from the bundled library. Each entry describes the procedure and links to its full usage instructions and supporting files on GitHub. Use **Customize → Skills** or `openscience skill list --all` for the library available in your installed version. A listed skill is a procedure, not a claim that all of its software, data, or services are installed. @@ -15,29 +15,42 @@ For example: "Use peer-review on drafts/paper.md. Save prioritized findings with See [Skills](/openscience/skills) for installation and authoring, and [Skill recipes](/openscience/skill-workflows) for complete example requests. The summaries below describe skill instructions, not a guarantee of installed software, account access, or current third-party product terms. +## Where the skills come from + +Most of these skills were written by other people and adapted for OpenScience's tools: [Scientific Agent Skills](https://github.com/K-Dense-AI/scientific-agent-skills) and [Claude Scientific Writer](https://github.com/K-Dense-AI/claude-scientific-writer) by K-Dense Inc. (MIT), [AI Research Skills](https://github.com/Orchestra-Research/AI-Research-SKILLs) by Orchestra Research (MIT), [Hugging Face skills](https://github.com/huggingface/skills) (Apache-2.0), Anthropic's document skills, and the [NVIDIA BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). Each skill's frontmatter names its original author, and [ATTRIBUTION.md](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ATTRIBUTION.md) lists every derived skill with its upstream path and license. If a K-Dense skill contributes to published work, cite [Kassis et al. (2026)](https://arxiv.org/abs/2609.00065). + ## Biology | Skill and usage instructions | What the procedure covers | | --- | --- | | [anndata](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/anndata/SKILL.md) | Data structure for annotated matrices in single-cell analysis. | | [benchling-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/benchling-integration/SKILL.md) | Benchling R&D platform integration. | +| [bids](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/bids/SKILL.md) | Use this skill when working with Brain Imaging Data Structure (BIDS) datasets: organizing neuroscience and biomedical data (MRI, EEG, MEG, iEEG, PET, microscopy, NIRS, motion capture, EMG, MR spectroscopy, behavioral), querying BIDS layouts, validating… | | [bioimage-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/bioimage-analysis/SKILL.md) | Microscopy image analysis for cell biology. | +| [bionemo-nims](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/bionemo-nims/SKILL.md) | Run NVIDIA BioNeMo NIMs through the hosted scientific_capability tool with your own NVIDIA API key. | | [biopython](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/biopython/SKILL.md) | Comprehensive molecular biology toolkit. | | [bioservices](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/bioservices/SKILL.md) | Unified Python interface to 40+ bioinformatics services. | +| [bulk-rnaseq](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/bulk-rnaseq/SKILL.md) | End-to-end bulk RNA-seq orchestrator — takes raw FASTQ reads through QC and trimming (FastQC, fastp/Trim Galore), alignment and quantification (STAR, Salmon, featureCounts), assembles a gene-level counts matrix, then hands off to differential expression… | | [cancer-genomics-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/cancer-genomics-analysis/SKILL.md) | Computational cancer genomics workflows. | | [clinical-decision-support](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/clinical-decision-support/SKILL.md) | Generate professional clinical decision support (CDS) documents for pharmaceutical and clinical research settings, including patient cohort analyses (biomarker-stratified with outcomes) and treatment recommendation reports (evidence-based guidelines with… | | [clinical-imaging](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/clinical-imaging/SKILL.md) | Clinical and physiological imaging analysis. | | [clinical-reports](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/clinical-reports/SKILL.md) | Write comprehensive clinical reports including case reports (CARE guidelines), diagnostic reports (radiology/pathology/lab), clinical trial reports (ICH-E3, SAE, CSR), and patient documentation (SOAP, H&P, discharge summaries). | | [cobrapy](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/cobrapy/SKILL.md) | Constraint-based metabolic modeling (COBRA). | | [curated-bio-datasets](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/curated-bio-datasets/SKILL.md) | Guide to accessing curated biological datasets for computational biology. | +| [deepspot-m](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/deepspot-m/SKILL.md) | Generate transcriptome-wide virtual spatial transcriptomics from H&E histology with DeepSpot-M. | | [deeptools](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/deeptools/SKILL.md) | NGS analysis toolkit. | | [dnanexus-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/dnanexus-integration/SKILL.md) | DNAnexus cloud genomics platform. | | [esm](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/esm/SKILL.md) | Comprehensive toolkit for protein language models including ESM3 (generative multimodal protein design across sequence, structure, and function) and ESM C (efficient protein embeddings and representations). | | [etetoolkit](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/etetoolkit/SKILL.md) | Phylogenetic tree toolkit (ETE). | | [flow-cytometry-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/flow-cytometry-analysis/SKILL.md) | Complete flow cytometry analysis pipeline. | | [flowio](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/flowio/SKILL.md) | Parse FCS (Flow Cytometry Standard) files v2.0-3.1. | +| [folklore-variant-evidence](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/folklore-variant-evidence/SKILL.md) | Retrieve ClinGen gene-disease validity assertions for a public gene or disease, and review source-linked public evidence and literature for one supported GRCh38 germline nuclear SNV or simple indel through Folklore Clinical Variant Interpretation MCP. | +| [genomic-coordinates](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/genomic-coordinates/SKILL.md) | Convert genomic intervals between coordinate conventions, normalise and compare variant representations, and detect assembly or contig-naming mismatches before they corrupt an analysis. | +| [genomic-intelligence](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/genomic-intelligence/SKILL.md) | Predict regulatory features, gene structure, and expression directly from DNA sequence using Genomic Intelligence's hosted transformer DNA language models — no local GPU or model weights. | | [gget](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/gget/SKILL.md) | Fast CLI/Python queries to 20+ bioinformatics databases. | +| [ginkgo-cloud-lab](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/ginkgo-cloud-lab/SKILL.md) | Submit and manage protocols on Ginkgo Bioworks Cloud Lab (cloud.ginkgo.bio), a web-based interface for autonomous lab execution on Reconfigurable Automation Carts (RACs). | | [glycobiology](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/glycobiology/SKILL.md) | Glycosylation site prediction and glycobiology analysis. | +| [glycoengineering](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/glycoengineering/SKILL.md) | Analyze and engineer protein glycosylation. | | [histolab](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/histolab/SKILL.md) | Lightweight WSI tile extraction and preprocessing. | | [immunology-assays](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/immunology-assays/SKILL.md) | Computational analysis of immunology experimental data. | | [lamindb](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/lamindb/SKILL.md) | This skill should be used when working with LaminDB, an open-source data framework for biology that makes data queryable, traceable, reproducible, and FAIR. | @@ -46,10 +59,16 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | [molecular-cloning](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/molecular-cloning/SKILL.md) | Molecular cloning simulation and design. | | [neurokit2](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/neurokit2/SKILL.md) | Comprehensive biosignal processing toolkit for analyzing physiological data including ECG, EEG, EDA, RSP, PPG, EMG, and EOG signals. | | [neuropixels-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/neuropixels-analysis/SKILL.md) | Neuropixels neural recording analysis. | +| [nextflow](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/nextflow/SKILL.md) | Build, run, and debug Nextflow data pipelines and nf-core workflows end to end. | | [omero-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/omero-integration/SKILL.md) | Microscopy data management platform. | | [opentrons-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/opentrons-integration/SKILL.md) | Official Opentrons Protocol API for OT-2 and Flex robots. | +| [pacsomatic](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pacsomatic/SKILL.md) | Operator toolkit for nf-core/pacsomatic matched tumor-normal workflows from BAM inputs. | | [pathml](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pathml/SKILL.md) | Full-featured computational pathology toolkit. | +| [pathogen-variant-surveillance](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pathogen-variant-surveillance/SKILL.md) | Query live pathogen genomic surveillance data through the GenSpectrum LAPIS API to find which viral lineages are circulating now, how fast they are growing, and what mutations they carry. | +| [pathway-enrichment](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pathway-enrichment/SKILL.md) | Run pathway and gene-set enrichment analysis on gene lists or ranked gene data, then interpret the results. | | [pharmacology-wetlab](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pharmacology-wetlab/SKILL.md) | Computational analysis of pharmacology wet-lab experiments. | +| [phylogenetics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/phylogenetics/SKILL.md) | Build and analyze phylogenetic trees using MAFFT (multiple alignment), IQ-TREE 2 (maximum likelihood), and FastTree (fast NJ/ML). | +| [polars-bio](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/polars-bio/SKILL.md) | High-performance genomic interval operations and bioinformatics file I/O on Polars DataFrames. | | [protein-binder-design](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/protein-binder-design/SKILL.md) | Design and validate de novo protein binders with the current NVIDIA BioNeMo Agent Toolkit workflow, while adapting honestly when NVIDIA-hosted credentials are unavailable. | | [protocolsio-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/protocolsio-integration/SKILL.md) | Integration with protocols.io API for managing scientific protocols. | | [pydeseq2](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pydeseq2/SKILL.md) | Differential gene expression analysis (Python DESeq2). | @@ -57,12 +76,18 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | [pyhealth](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pyhealth/SKILL.md) | Comprehensive healthcare AI toolkit for developing, testing, and deploying machine learning models with clinical data. | | [pylabrobot](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pylabrobot/SKILL.md) | Vendor-agnostic lab automation framework. | | [pysam](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pysam/SKILL.md) | Genomic file toolkit. | +| [relsa-severity-assessment](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/relsa-severity-assessment/SKILL.md) | Multivariate severity assessment and humane endpoint prediction for laboratory animal studies using the RELSA (RELative Severity Assessment) score and ARIMA-based foRcast forecasting. | | [scanpy](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/scanpy/SKILL.md) | Standard single-cell RNA-seq analysis pipeline. | | [scikit-bio](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/scikit-bio/SKILL.md) | Biological data toolkit. | | [scikit-survival](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/scikit-survival/SKILL.md) | Comprehensive toolkit for survival analysis and time-to-event modeling in Python using scikit-survival. | +| [scvelo](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/scvelo/SKILL.md) | RNA velocity analysis with scVelo. | | [scvi-tools](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/scvi-tools/SKILL.md) | Deep generative models for single-cell omics. | +| [structure-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/structure-analysis/SKILL.md) | Handles protein structure files and geometric criteria so that residue counts, contacts, hydrogen bonds and interfaces are reproducible, covering PDB versus mmCIF, author versus label chains and numbering, HETATM, water and ligand policy, alternate… | | [synthetic-biology](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/synthetic-biology/SKILL.md) | Synthetic biology design and simulation tools. | +| [tamarind](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/tamarind/SKILL.md) | Access a collection of open-source molecular design and structural biology tools on the Tamarind Bio platform, via its REST API or MCP server — no local GPUs required. | +| [tiledbvcf](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/tiledbvcf/SKILL.md) | Efficient storage and retrieval of genomic variant data using TileDB. | | [treatment-plans](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/treatment-plans/SKILL.md) | Generate concise (3-4 page), focused medical treatment plans in LaTeX/PDF format for all clinical specialties. | +| [waypoint-bio](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/waypoint-bio/SKILL.md) | Use when working with Outpost Bio's open microbiome foundation models - the Waypoint checkpoints (Waypoint-6m, Waypoint-45m, Waypoint-170m), the Atlas pretraining corpus, the Compass eight-task benchmark, or the `waypoint` CLI from the `waypoint-bio` package. | ## Chemistry @@ -70,7 +95,10 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | --- | --- | | [admet-prediction](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/admet-prediction/SKILL.md) | ADMET property prediction for drug candidates. | | [admet-reasoning](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/admet-reasoning/SKILL.md) | Interpretable ADMET analysis with mechanistic reasoning. | +| [analytical-method-validation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/analytical-method-validation/SKILL.md) | Plan, execute, and document validation, verification, and transfer of analytical procedures under the governing framework - ICH Q2(R2) and Q14, USP <1220>/<1225>/<1226>, ICH M10 bioanalytical, CLSI EP, or ISO/IEC 17025. | +| [atomistic-workflows](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/atomistic-workflows/SKILL.md) | Sets up and reports atomistic calculations so they are reproducible and converged, covering ASE Atoms, calculators, optimizers and MD drivers, pymatgen structures, symmetry analysis and the Materials Project API, LAMMPS and GROMACS input basics for… | | [binding-affinity](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/binding-affinity/SKILL.md) | Empirical affinity estimates, ligand energy inspection, docking-score consensus, and batch virtual screening. | +| [cheminformatics-definitions](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/cheminformatics-definitions/SKILL.md) | Pins down the RDKit definitions that differ between conventions before computing molecular descriptors, including Lipinski donor and acceptor counts (Lipinski.NumHDonors and NumHAcceptors versus rdMolDescriptors.CalcNumLipinskiHBD and HBA), TPSA with or… | | [datamol](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/datamol/SKILL.md) | Pythonic wrapper around RDKit with simplified interface and sensible defaults. | | [deepchem](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/deepchem/SKILL.md) | Molecular ML with diverse featurizers and pre-built datasets. | | [denovo-design](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/denovo-design/SKILL.md) | De novo molecule generation for drug discovery. | @@ -80,10 +108,12 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | [matchms](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/matchms/SKILL.md) | Spectral similarity and compound identification for metabolomics. | | [medchem](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/medchem/SKILL.md) | Medicinal chemistry filters. | | [molecular-docking](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/molecular-docking/SKILL.md) | End-to-end molecular docking pipeline. | +| [molecular-dynamics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/molecular-dynamics/SKILL.md) | Run and analyze molecular dynamics simulations with OpenMM and MDAnalysis. | | [molecular-optimization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/molecular-optimization/SKILL.md) | Iterative lead optimization with analyze-reason-generate-verify-evaluate loop. | | [molecular-rag](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/molecular-rag/SKILL.md) | Retrieve structurally similar compounds with known properties from ChEMBL/ZINC to ground predictions and inform optimization. | | [molecule-visualization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/molecule-visualization/SKILL.md) | Publication-quality molecular visualization. | | [molfeat](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/molfeat/SKILL.md) | Molecular featurization for ML (100+ featurizers). | +| [pkpd-modeling](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/pkpd-modeling/SKILL.md) | Pharmacokinetic and pharmacodynamic modelling and simulation - non-compartmental analysis, compartmental and population PK, PK/PD and exposure-response, TMDD, PBPK orientation, bioequivalence, allometric scaling and first-in-human dose, drug interaction… | | [pocket-detection](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/pocket-detection/SKILL.md) | Multi-method binding pocket detection and druggability assessment. | | [pyopenms](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/pyopenms/SKILL.md) | Complete mass spectrometry analysis platform. | | [pytdc](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/pytdc/SKILL.md) | Therapeutics Data Commons. | @@ -104,6 +134,7 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | [matlab](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/matlab/SKILL.md) | MATLAB and GNU Octave numerical computing for matrix operations, data analysis, visualization, and scientific computing. | | [multi-objective-optimization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/multi-objective-optimization/SKILL.md) | Pareto-aware molecular design balancing multiple ADMET properties simultaneously. | | [networkx](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/networkx/SKILL.md) | Comprehensive toolkit for creating, analyzing, and visualizing complex networks and graphs in Python. | +| [optimize-for-gpu](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/optimize-for-gpu/SKILL.md) | GPU-accelerates scientific Python on NVIDIA hardware and verifies that the result is correct and faster. | | [pymc-bayesian-modeling](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/pymc/SKILL.md) | Bayesian modeling with PyMC. | | [pymoo](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/pymoo/SKILL.md) | Multi-objective optimization framework. | | [rowan](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/rowan/SKILL.md) | Cloud-based quantum chemistry platform with Python API. | @@ -114,6 +145,7 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | [statistical-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/statistical-analysis/SKILL.md) | Guided statistical analysis with test selection and reporting. | | [statsmodels](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/statsmodels/SKILL.md) | Statistical models library for Python. | | [sympy](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/sympy/SKILL.md) | Use this skill when working with symbolic mathematics in Python. | +| [timesfm-forecasting](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/timesfm-forecasting/SKILL.md) | Zero-shot time series forecasting with Google's TimesFM foundation model. | | [torch-geometric](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/torch_geometric/SKILL.md) | Graph Neural Networks (PyG). | | [umap-learn](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/umap-learn/SKILL.md) | UMAP dimensionality reduction. | @@ -133,12 +165,37 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | [together-ai-inference](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/together-ai/SKILL.md) | Use your Together account for supported inference, embeddings, and fine-tuning workflows. | | [vast-ai-gpu-cloud](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/vast-ai/SKILL.md) | Safely inspect and operate Vast.ai marketplace instances with the vastai CLI, live offer data, and explicit approval before paid or destructive actions. | +## core + +| Skill and usage instructions | What the procedure covers | +| --- | --- | +| [autoresearch](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/autoresearch/SKILL.md) | Runs a hill-climbing study over many training or analysis runs with the study and experiments tools, one metric and direction, a baseline, ideas ranked by expected value, exactly one run per idea, kill criteria and a budget, verdicts with analysis and… | +| [brainstorming](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/brainstorming/SKILL.md) | Generates and selects research directions, mapping what is known and what is open, producing many candidate ideas by named moves (gap, transfer, inversion, constraint change, scale, failure analysis), then ranking them by tractability and value and… | +| [citations](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/citations/SKILL.md) | Resolves, verifies and formats references, every citation confirmed against Crossref, OpenAlex, arXiv or PubMed before it enters the bibliography, BibTeX built from resolved metadata, and existing .bib files audited for fabricated or mismatched entries. | +| [compute](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/compute/SKILL.md) | Chooses and runs compute for research work, local shell or kernel versus a detached compute_job on this machine, a saved SSH or Slurm host, or Modal GPUs, with the target discovered from what is actually configured, the run sized and priced before… | +| [delegation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/delegation/SKILL.md) | Delegates independent work to worker agents through the Task tool, choosing between the explore scout and the ml, biology, physics, chemistry and data specialists, writing a self-contained brief for a worker that cannot see the conversation, setting… | +| [execution-hygiene](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/execution-hygiene/SKILL.md) | Runs computations so they finish, reproduce and fit the machine that will re-execute them, detaching long jobs through compute_job instead of blocking or sleeping shells, checkpointing so reruns resume, fixing seeds and capping BLAS and OpenMP threads,… | +| [figures](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/figures/SKILL.md) | Makes publication-quality plots from data with matplotlib, learning curves, scaling laws, benchmark and ablation comparisons, Pareto trade-offs, heatmaps and confusion matrices, sized for the page, vector, with uncertainty shown. | +| [generate-image](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/generate-image/SKILL.md) | Generate illustrations, graphical abstracts and image edits with generate_image through Ace or a Gemini or OpenAI key. | +| [hypotheses](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/hypotheses/SKILL.md) | Turns a research direction into testable hypotheses with predictions, competing explanations and the experiments that discriminate between them, including the design (controls, randomization, blocking), sample size or seed count, the pre-specified… | +| [literature-review](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/literature-review/SKILL.md) | Finds, ranks and reads the literature on a question, the retrieval loop the lead runs itself over OpenAlex, arXiv, Crossref, PubMed and bioRxiv with a fixed budget, deduplication, ranking by topical fit, reading of the load-bearing papers and claim-level… | +| [ml-paper-writing](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/ml-paper-writing/SKILL.md) | Writes and revises machine-learning papers for NeurIPS, ICML, ICLR, ACL, COLM and AAAI, from a research repository or a set of tracked runs to a compiling LaTeX draft in the venue's template, with the contribution stated as claims backed by experiments,… | +| [paper-writing](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/paper-writing/SKILL.md) | Writes and revises scientific manuscripts, journal articles, preprints, theses, reports, in full paragraphs with the argument built from the project's actual results and sources, as a real .tex or .md file in the working folder. | +| [peer-review](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/peer-review/SKILL.md) | Reviews a manuscript, proposal, analysis or result the way a careful referee does, reading the whole artifact, checking the methods against the claims, the statistics against the design, the figures against the numbers, and reporting BLOCKING issues… | +| [reproduce](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/reproduce/SKILL.md) | Reproduces a paper's result, a claim, an artifact or a previous run with the target and success criterion frozen first, the canonical code path run before any substitute, exact inputs, environment, seeds and commands captured, and a verdict from a fixed… | +| [research-lookup](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/research-lookup/SKILL.md) | Find current research and technical references with configured search access and citations. | +| [schematics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/schematics/SKILL.md) | Creates or refines publication-quality technical diagrams with the native generate_image tool (Nano Banana Pro through Ace or a Gemini key, GPT Image 2 through an OpenAI key), method and architecture overviews, pipelines, CONSORT and PRISMA flows,… | +| [scientific-visualization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/scientific-visualization/SKILL.md) | Creates and audits truthful, accessible, publication-ready scientific figures with Matplotlib, Seaborn or Plotly, covering figure design, multi-panel layouts, uncertainty and missing-data displays, colour and contrast review, image metadata validation and… | +| [sources](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/core/sources/SKILL.md) | Audits claims against their sources, each statement in a draft, report, answer or summary traced to the passage, table, dataset or run that supports it, and marked supported, partially supported, unsupported or contradicted, with a provenance table as the… | + ## Data engineering | Skill and usage instructions | What the procedure covers | | --- | --- | | [aeon](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/aeon/SKILL.md) | This skill should be used for time series machine learning tasks including classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search. | | [dask](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/dask/SKILL.md) | Distributed computing for larger-than-RAM pandas/NumPy workflows. | +| [datalad](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/datalad/SKILL.md) | Retrieve, version, and publish scientific datasets with DataLad and git-annex, and capture computational provenance with datalad run, rerun, and containers-run. | +| [geomaster](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/geomaster/SKILL.md) | Comprehensive geospatial science skill covering remote sensing, GIS, spatial analysis, machine learning for earth observation, and 30+ scientific domains. | | [geopandas](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/geopandas/SKILL.md) | Python library for working with geospatial vector data including shapefiles, GeoJSON, and GeoPackage files. | | [hdf5-pde-data-loading](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/hdf5-pde-data-loading/SKILL.md) | Patterns for loading PDE simulation datasets (PDEBench, PhiFlow, JAX-CFD) from HDF5 files. | | [hugging-face-datasets](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/hugging-face-datasets/SKILL.md) | Create and manage datasets on Hugging Face Hub. | @@ -161,7 +218,9 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | [clinpgx-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/clinpgx-database/SKILL.md) | Access ClinPGx pharmacogenomics data (successor to PharmGKB). | | [clinvar-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/clinvar-database/SKILL.md) | Query NCBI ClinVar for variant clinical significance. | | [cosmic-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/cosmic-database/SKILL.md) | Access COSMIC cancer mutation database. | +| [database-lookup](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/database-lookup/SKILL.md) | Query documented public database APIs with explicit endpoints, filters, pagination, and provenance. | | [datacommons-client](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/datacommons-client/SKILL.md) | Work with Data Commons, a platform providing programmatic access to public statistical data from global sources. | +| [depmap](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/depmap/SKILL.md) | Query the Cancer Dependency Map (DepMap) for cancer cell line gene dependency scores (CRISPR Chronos), drug sensitivity data, and gene effect profiles. | | [drugbank-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/drugbank-database/SKILL.md) | Access and analyze comprehensive drug information from the DrugBank database including drug properties, interactions, targets, pathways, chemical structures, and pharmacology data. | | [ena-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/ena-database/SKILL.md) | Access European Nucleotide Archive via API/FTP. | | [ensembl-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/ensembl-database/SKILL.md) | Query Ensembl genome database REST API for 250+ species. | @@ -174,33 +233,42 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | [imaging-data-commons](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/imaging-data-commons/SKILL.md) | Query and download public cancer imaging data from NCI Imaging Data Commons using idc-index. | | [kegg-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/kegg-database/SKILL.md) | Direct REST API access to KEGG (academic use only). | | [metabolomics-workbench-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/metabolomics-workbench-database/SKILL.md) | Access NIH Metabolomics Workbench via REST API (4,200+ studies). | +| [ncats-arax](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/ncats-arax/SKILL.md) | Queries the NCATS Translator ARAX production API for bounded, typed, provenance-rich one-hop and endpoint-pinned two-hop biomedical knowledge-graph relationships. | +| [onekgpd](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/onekgpd/SKILL.md) | Query the 1000 Genomes Project dataset (3,202 whole-genome-sequenced individuals, GRCh38) at the level of individual participants. | +| [ontology-term-resolution](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/ontology-term-resolution/SKILL.md) | Resolve free-text scientific labels to ontology term IDs and validate existing CURIEs against the EBI Ontology Lookup Service (OLS4). | | [openalex-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/openalex-database/SKILL.md) | Query and analyze scholarly literature using the OpenAlex database. | | [opentargets-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/opentargets-database/SKILL.md) | Query Open Targets Platform for target-disease associations, drug target discovery, tractability/safety data, genetics/omics evidence, known drugs, for therapeutic target identification. | | [pdb-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/pdb-database/SKILL.md) | Access RCSB PDB for 3D protein/nucleic acid structures. | +| [primekg](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/primekg/SKILL.md) | Query the Precision Medicine Knowledge Graph (PrimeKG) for multiscale biological data including genes, drugs, diseases, phenotypes, and more. | | [pubchem-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/pubchem-database/SKILL.md) | Query PubChem via PUG-REST API/PubChemPy (110M+ compounds). | | [pubmed-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/pubmed-database/SKILL.md) | Direct REST API access to PubMed. | | [reactome-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/reactome-database/SKILL.md) | Query Reactome REST API for pathway analysis, enrichment, gene-pathway mapping, disease pathways, molecular interactions, expression analysis, for systems biology studies. | | [string-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/string-database/SKILL.md) | Query STRING API for protein-protein interactions (59M proteins, 20B interactions). | | [uniprot-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/uniprot-database/SKILL.md) | Direct REST API access to UniProt. | +| [usfiscaldata](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/usfiscaldata/SKILL.md) | Query the U.S. | | [uspto-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/uspto-database/SKILL.md) | Access USPTO APIs for patent/trademark searches, examination history (PEDS), assignments, citations, office actions, TSDR, for IP analysis and prior art searches. | | [zinc-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/zinc-database/SKILL.md) | Access ZINC (230M+ purchasable compounds). | +## document-parsing + +| Skill and usage instructions | What the procedure covers | +| --- | --- | +| [docx](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/document-parsing/docx/SKILL.md) | Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). | +| [pdf](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/document-parsing/pdf/SKILL.md) | Use this skill whenever the user wants to do anything with PDF files. | +| [pptx](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/document-parsing/pptx/SKILL.md) | Use this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. | +| [xlsx](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/document-parsing/xlsx/SKILL.md) | Create, edit, analyze, or convert Excel spreadsheets (.xlsx, .xlsm, .xltx) where the workbook file is the primary deliverable. | + ## General | Skill and usage instructions | What the procedure covers | | --- | --- | | [checkpoint](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/checkpoint/SKILL.md) | Save a local recovery packet from durable session state. | | [compact](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/compact/SKILL.md) | Compact the current chat context into a concise summary. | -| [conducting-scientific-research](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/conducting-scientific-research/SKILL.md) | Conduct rigorous, reproducible multi-step scientific work with literature, databases, local files, Python, R, shell, artifacts, reviewers, and approved compute. | -| [context](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/context/SKILL.md) | Show the current conversation context composition, estimated capacity, and compaction state. | | [goal](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/goal/SKILL.md) | Set an explicit objective, success criteria, and stopping conditions for the current OpenScience session. | | [handoff](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/handoff/SKILL.md) | Create a self-contained continuation packet for another agent. | | [init](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/init/SKILL.md) | Create or refresh an AGENTS.md project instruction file. | | [liteparse](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/document-parsing/liteparse/SKILL.md) | Use this skill when the user asks to parse, perform multi-format document conversion or spatially extract text from an unstructured file (PDF, DOCX, PPTX, XLSX, images, etc.) locally without cloud dependencies. | | [plan](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/plan/SKILL.md) | Enter read-only plan mode and produce a decision-ready plan. | -| [resume](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/resume/SKILL.md) | Resume an exhausted bounded research run from its existing contract and checkpoints. | -| [scientific-problem-selection](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/scientific-problem-selection/SKILL.md) | This skill should be used when scientists need help with research problem selection, project ideation, troubleshooting stuck projects, or strategic scientific decisions. | -| [status](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/status/SKILL.md) | Show live session, plan, artifact, model, and workspace state. | | [stop](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/stop/SKILL.md) | Stop active work in the current conversation and check the state of ongoing jobs. | ## Language model tools @@ -215,7 +283,6 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | [crewai-multi-agent](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/crewai/SKILL.md) | Multi-agent orchestration framework for autonomous AI collaboration. | | [dspy](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/dspy/SKILL.md) | Build complex AI systems with declarative programming, optimize prompts automatically, create modular RAG systems and agents with DSPy - Stanford NLP's framework for systematic LM programming | | [faiss](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/faiss/SKILL.md) | Facebook's library for efficient similarity search and clustering of dense vectors. | -| [generate-image](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/generate-image/SKILL.md) | Generate or edit illustrations and other images with configured image access. | | [guidance](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/guidance/SKILL.md) | Control LLM output with regex and grammars, guarantee valid JSON/XML/code generation, enforce structured formats, and build multi-step workflows with Guidance - Microsoft Research's constrained generation framework | | [hugging-face-cli](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/hugging-face-cli/SKILL.md) | Execute Hugging Face Hub operations using the `hf` CLI. | | [hugging-face-tool-builder](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/hugging-face-tool-builder/SKILL.md) | Use this skill when the user wants to build tool/scripts or achieve a task where using data from the Hugging Face API would help. | @@ -314,40 +381,49 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | Skill and usage instructions | What the procedure covers | | --- | --- | +| [coq](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/coq/SKILL.md) | Develops and checks proofs in Coq and its renamed successor Rocq, covering the `_CoqProject` and `coq_makefile` (or `rocq makefile`) build, `coqc` and `coqchk` (or `rocq compile` and `rocq check`), finding lemmas with `Search` and `SearchPattern`, choosing… | | [get-available-resources](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/get-available-resources/SKILL.md) | This skill should be used at the start of any computationally intensive scientific task to detect and report available system resources (CPU cores, GPUs, memory, disk space). | | [hugging-face-jobs](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/hugging-face-jobs/SKILL.md) | This skill should be used when users want to run any workload on Hugging Face Jobs infrastructure. | | [hugging-face-trackio](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/hugging-face-trackio/SKILL.md) | Track and visualize ML training experiments with Trackio. | | [iso-13485-certification](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/iso-13485-certification/SKILL.md) | Comprehensive toolkit for preparing ISO 13485 certification documentation for medical device Quality Management Systems. | +| [iso-standards-readiness](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/iso-standards-readiness/SKILL.md) | Prepares and structurally reviews readiness evidence for ISO management-system and laboratory-competence standards - ISO 13485 medical device QMS, ISO 14971 device risk management, ISO/IEC 17025 testing and calibration laboratories, and ISO 15189 medical… | +| [lab-hardware-cad](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/lab-hardware-cad/SKILL.md) | Design custom laboratory hardware as parametric build123d models and export fabrication-ready STEP, STL, and DXF files - microfluidic chips and molds, optomechanical mounts and breadboard adapters, cuvette and microplate holders, tube racks,… | | [labarchive-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/labarchive-integration/SKILL.md) | Electronic lab notebook API integration. | +| [lean4-mathlib](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/lean4-mathlib/SKILL.md) | Formalizes and checks mathematical statements in Lean 4 with Mathlib, covering the lake project layout and pinned toolchain, `lake exe cache get` before `lake build`, searching Mathlib through Loogle, `exact?`, `apply?` and `simp?`, tactic hygiene,… | | [skill-installer](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/skill-installer/SKILL.md) | Install or remove third-party openscience skills from a public git repository. | ## Physics | Skill and usage instructions | What the procedure covers | | --- | --- | +| [astronomy-inference](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/astronomy-inference/SKILL.md) | Carries astronomical data from file to posterior with the conventions the field expects, covering astropy units, coordinates, FITS, WCS and Time with barycentric corrections, photometric systems and magnitude arithmetic, period finding with the astropy… | | [astropy](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/astropy/SKILL.md) | Comprehensive Python library for astronomy and astrophysics. | | [autoregressive-neural-pde-solver](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/autoregressive-neural-pde-solver/SKILL.md) | Training patterns for autoregressive neural PDE solvers (FNO, DeepONet, CNO). | | [bayesian-inference](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/bayesian-inference/SKILL.md) | Bayesian parameter estimation with MCMC (emcee) and probabilistic programming (PyMC). | | [conservation-law-discovery](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/conservation-law-discovery/SKILL.md) | Discover conserved quantities and symmetries from trajectory data. | -| [dimensional-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/dimensional-analysis/SKILL.md) | Automated dimensional analysis: Buckingham Pi theorem, non-dimensionalization, unit validation with pint, and characteristic scale estimation. | -| [dynamical-systems](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/dynamical-systems/SKILL.md) | Analyze nonlinear dynamical systems: phase portraits, fixed points, stability analysis, bifurcation diagrams, Poincare sections, Lyapunov exponents, and chaos detection. | -| [fluid-dynamics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/fluid-dynamics/SKILL.md) | Computational fluid dynamics: Navier-Stokes solvers, lid-driven cavity, channel flow, vortex methods, turbulence statistics, drag/lift computation. | +| [dimensional-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/dimensional-analysis/SKILL.md) | Automated dimensional analysis — Buckingham Pi theorem, non-dimensionalization, unit validation with pint, and characteristic scale estimation. | +| [dynamical-systems](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/dynamical-systems/SKILL.md) | Analyze nonlinear dynamical systems — phase portraits, fixed points, stability analysis, bifurcation diagrams, Poincare sections, Lyapunov exponents, and chaos detection. | +| [energy-systems](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/energy-systems/SKILL.md) | Applies energy-systems modelling conventions so that capacity, energy, cost and emissions numbers are consistent and comparable, covering kW versus kWh and MW versus MWh, capacity versus energy, capacity factors, load duration curves, the LCOE formula with… | +| [fluid-dynamics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/fluid-dynamics/SKILL.md) | Computational fluid dynamics — Navier-Stokes solvers, lid-driven cavity, channel flow, vortex methods, turbulence statistics, drag/lift computation. | | [fluidsim](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/fluidsim/SKILL.md) | Framework for computational fluid dynamics simulations using Python. | -| [hamiltonian-mechanics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/hamiltonian-mechanics/SKILL.md) | Hamiltonian mechanics: symplectic integrators (leapfrog, Yoshida), Hamilton's equations, Poisson brackets, canonical transformations, action-angle variables, and KAM theory analysis. | +| [geoscience-data](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/geoscience-data/SKILL.md) | Reads, transforms and summarizes gridded and geospatial data without losing the metadata that gives it meaning, covering NetCDF and HDF5 through xarray and netCDF4 with CF conventions, dimensions versus coordinates, time encodings and calendars and fill… | +| [hamiltonian-mechanics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/hamiltonian-mechanics/SKILL.md) | Hamiltonian mechanics — symplectic integrators (leapfrog, Yoshida), Hamilton's equations, Poisson brackets, canonical transformations, action-angle variables, and KAM theory analysis. | | [neural-operator](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/neural-operator/SKILL.md) | Train neural operators (FNO, DeepONet) to learn solution maps for parametric PDE families. | | [ode-solver](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/ode-solver/SKILL.md) | Solve ordinary differential equations (initial and boundary value problems). | -| [pde-solver](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/pde-solver/SKILL.md) | Solve partial differential equations: finite differences, spectral methods, and physics-informed neural networks (PINNs via DeepXDE). | -| [physics-databases](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/physics-databases/SKILL.md) | Query physics databases: NIST CODATA constants, NIST Chemistry WebBook, Materials Project, Particle Data Group (PDG), OEIS sequences. | +| [openpiv](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/openpiv/SKILL.md) | Particle Image Velocimetry (PIV) analysis with OpenPIV. | +| [pde-solver](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/pde-solver/SKILL.md) | Solve partial differential equations — finite differences, spectral methods, and physics-informed neural networks (PINNs via DeepXDE). | +| [physics-databases](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/physics-databases/SKILL.md) | Query physics databases — NIST CODATA constants, NIST Chemistry WebBook, Materials Project, Particle Data Group (PDG), OEIS sequences. | | [physics-fitting](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/physics-fitting/SKILL.md) | Nonlinear curve fitting for physics data with proper error propagation, chi-squared analysis, residual diagnostics, confidence intervals, and model comparison (AIC/BIC). | -| [physics-visualization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/physics-visualization/SKILL.md) | Publication-quality physics plots: vector fields, streamlines, contour maps, 3D surfaces, phase space, spectrograms, and animations. | +| [physics-visualization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/physics-visualization/SKILL.md) | Publication-quality physics plots — vector fields, streamlines, contour maps, 3D surfaces, phase space, spectrograms, and animations. | | [pinn-training](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/pinn-training/SKILL.md) | Train Physics-Informed Neural Networks (PINNs) using DeepXDE. | | [pymatgen](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/pymatgen/SKILL.md) | Materials science toolkit. | | [shock-capturing-neural-operators](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/shock-capturing-neural-operators/SKILL.md) | Architectures and techniques for neural operators on discontinuous PDE solutions (shocks, contact discontinuities, steep gradients). | -| [sindy-identification](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/sindy-identification/SKILL.md) | Sparse Identification of Nonlinear Dynamics (SINDy): discover governing equations from time-series data. | -| [spectral-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/spectral-analysis/SKILL.md) | Frequency-domain analysis: FFT, power spectral density (Welch/periodogram), spectrograms, wavelet transforms, and coherence. | -| [statistical-mechanics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/statistical-mechanics/SKILL.md) | Monte Carlo simulation for statistical mechanics: Ising model, Metropolis-Hastings, Wolff cluster algorithm, observables (magnetization, susceptibility, specific heat), finite-size scaling, and critical phenomena analysis. | +| [sindy-identification](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/sindy-identification/SKILL.md) | Sparse Identification of Nonlinear Dynamics (SINDy) — discover governing equations from time-series data. | +| [spectral-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/spectral-analysis/SKILL.md) | Frequency-domain analysis — FFT, power spectral density (Welch/periodogram), spectrograms, wavelet transforms, and coherence. | +| [statistical-mechanics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/statistical-mechanics/SKILL.md) | Monte Carlo simulation for statistical mechanics — Ising model, Metropolis-Hastings, Wolff cluster algorithm, observables (magnetization, susceptibility, specific heat), finite-size scaling, and critical phenomena analysis. | | [symbolic-regression](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/symbolic-regression/SKILL.md) | Discover governing equations from data using PySR (evolutionary symbolic regression). | -| [wave-propagation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/wave-propagation/SKILL.md) | Simulate wave propagation: acoustic, electromagnetic, elastic, and quantum waves. | +| [uncertainty-and-units](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/uncertainty-and-units/SKILL.md) | Track physical units and propagate measurement uncertainty in scientific calculations using pint and uncertainties. | +| [wave-propagation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/wave-propagation/SKILL.md) | Simulate wave propagation — acoustic, electromagnetic, elastic, and quantum waves. | ## Quantum science @@ -363,21 +439,17 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | Skill and usage instructions | What the procedure covers | | --- | --- | | [compare](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/compare/SKILL.md) | Compare runs, artifacts, methods, models, or claims on a fair and explicit decision basis. | +| [experimental-design](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/experimental-design/SKILL.md) | Design experiments and studies BEFORE data is collected — choosing a design, randomizing, blocking, and laying out treatment combinations so results are interpretable. | | [export](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/export/SKILL.md) | Package results with provenance, reproduction instructions, declared gaps, and the requested output format. | -| [hypothesis-generation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/hypothesis-generation/SKILL.md) | Generate testable hypotheses. | | [market-research-reports](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/market-research-reports/SKILL.md) | Generate comprehensive market research reports (50+ pages) in the style of top consulting firms (McKinsey, BCG, Gartner). | -| [peer-review](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/peer-review/SKILL.md) | Systematic peer review toolkit. | -| [perplexity-search](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/perplexity-search/SKILL.md) | Search for current information and source-backed answers using your configured search access. | -| [reproduce](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/reproduce/SKILL.md) | Reproduce a claim, paper result, artifact, or run with exact inputs, environment, criteria, and evidence. | +| [paper-lookup](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/paper-lookup/SKILL.md) | Search 18 scholarly APIs for papers, preprints, citations, open-access full text, repository records, and journal OA status, and return results with reproducible provenance. | +| [patent-mining](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/patent-mining/SKILL.md) | Retrieves and interprets patent data with the conventions that make counts and claims defensible, covering Google Patents, Lens, EPO Open Patent Services, USPTO data through PatentsView and the Open Data Portal, and WIPO PATENTSCOPE, together with kind… | | [research-grants](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/research-grants/SKILL.md) | Write competitive research proposals for NSF, NIH, DOE, and DARPA. | -| [research-lookup](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/research-lookup/SKILL.md) | Find current research and technical references with configured search access and citations. | | [research-workflows](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/research-workflows/SKILL.md) | Plan, review, verify, reproduce, compare, audit sources, and package scientific work. | | [review](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/review/SKILL.md) | Independently review code, results, claims, or an artifact and return prioritized, evidence-backed findings. | | [scholar-evaluation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/scholar-evaluation/SKILL.md) | Evaluate scholarly work with structured criteria for rigor, methodology, evidence, writing, and publication readiness. | -| [scientific-brainstorming](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/scientific-brainstorming/SKILL.md) | Creative research ideation and exploration. | -| [scientific-critical-thinking](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/scientific-critical-thinking/SKILL.md) | Evaluate research rigor. | -| [sources](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/sources/SKILL.md) | Audit sources, citations, and unsupported claims using a claim-level source ledger and primary evidence. | -| [verify](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/verify/SKILL.md) | Run real checks for a claim, implementation, result, or artifact and report pass, fail, or not tested. | +| [statistical-conventions](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/statistical-conventions/SKILL.md) | Chooses and reports statistical tests the way a careful referee expects, deciding paired versus unpaired and parametric versus rank-based from the design, using ordered-trend tests such as Jonckheere-Terpstra and Cochran-Armitage for dose or grade levels,… | +| [statistical-power](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/statistical-power/SKILL.md) | Sample-size and statistical power calculations for planning studies. | ## Visualization @@ -388,22 +460,18 @@ See [Skills](/openscience/skills) for installation and authoring, and [Skill rec | [matplotlib](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/matplotlib/SKILL.md) | Low-level plotting library for full customization. | | [plotly](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/plotly/SKILL.md) | Interactive visualization library. | | [protein-diagram](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/protein-diagram/SKILL.md) | Publication-quality protein analysis diagrams. | -| [scientific-schematics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/scientific-schematics/SKILL.md) | Create or refine publication-quality technical diagrams, scientific workflows, architectures, and biological schematics with the native image-generation capability. | -| [scientific-visualization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/scientific-visualization/SKILL.md) | Meta-skill for publication-ready figures. | | [seaborn](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/seaborn/SKILL.md) | Statistical visualization with pandas integration. | ## Writing | Skill and usage instructions | What the procedure covers | | --- | --- | -| [citation-management](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/citation-management/SKILL.md) | Comprehensive citation management for academic research. | +| [analysis-report](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/analysis-report/SKILL.md) | Writes the trace and report for an analysis whose output a reader will judge, restating the question with its binding clauses, recording data provenance, the method with every parameter that matters, results with raw and adjusted numbers and uncertainty,… | | [hugging-face-paper-publisher](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/hugging-face-paper-publisher/SKILL.md) | Publish and manage research papers on Hugging Face Hub. | | [latex-posters](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/latex-posters/SKILL.md) | Create professional research posters in LaTeX using beamerposter, tikzposter, or baposter. | -| [literature-review](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/literature-review/SKILL.md) | Answer literature-review requests with a concise, source-grounded narrative by default. | -| [ml-paper-writing](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/ml-paper-writing/SKILL.md) | Write publication-ready ML/AI papers for NeurIPS, ICML, ICLR, ACL, AAAI, COLM. | +| [markdown-mermaid-writing](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/markdown-mermaid-writing/SKILL.md) | Comprehensive markdown and Mermaid diagram writing skill. | | [paper-2-web](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/paper-2-web/SKILL.md) | This skill should be used when converting academic papers into promotional and presentation formats including interactive websites (Paper2Web), presentation videos (Paper2Video), and conference posters (Paper2Poster). | | [pptx-posters](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/pptx-posters/SKILL.md) | Create research posters using HTML/CSS that can be exported to PDF or PPTX. | +| [pyzotero](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/pyzotero/SKILL.md) | Interact with Zotero reference management libraries using the pyzotero Python client. | | [scientific-slides](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/scientific-slides/SKILL.md) | [EXPERIMENTAL] Build slide decks and presentations for research talks using Nano Banana Pro AI. | -| [scientific-writing](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/scientific-writing/SKILL.md) | Core skill for the deep research and writing tool. | -| [venue-templates](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/venue-templates/SKILL.md) | Access comprehensive LaTeX templates, formatting requirements, and submission guidelines for major scientific publication venues (Nature, Science, PLOS, IEEE, ACM), academic conferences (NeurIPS, ICML, CVPR, CHI), research posters, and grant proposals… | | [zotero-local](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/zotero-local/SKILL.md) | Read or search the user's local Zotero reference library when explicitly requested. | diff --git a/src/content/openscience/skill-workflows.mdx b/src/content/openscience/skill-workflows.mdx index c5c1011..ddb19da 100644 --- a/src/content/openscience/skill-workflows.mdx +++ b/src/content/openscience/skill-workflows.mdx @@ -9,11 +9,11 @@ The [complete directory](/openscience/skill-library) describes every bundled ski ## Plan and challenge an idea -Use scientific brainstorming for open-ended ideas, hypothesis generation for observations that need a testable explanation, and scientific critical thinking for evaluating a claim. +Use `brainstorming` for open-ended directions, `hypotheses` for observations that need a testable explanation and a discriminating experiment, and `peer-review` for evaluating a claim or a draft. ```text -Use hypothesis-generation on the observations in notes/pilot.md. Propose -three competing explanations, the evidence each predicts, and a small +Use hypotheses on the observations in notes/pilot.md. Propose three +competing explanations, the evidence each predicts, and a small experiment that distinguishes them. Save the comparison in methods/. ``` @@ -27,7 +27,7 @@ concerns from presentation issues, cite the relevant sections, and list the evidence or analysis needed to resolve each major concern. ``` -For a specific implementation or result, the `review` and `verify` procedures help organize findings and checks. Verification should state pass, fail, or not tested and name the evidence. +For a code change or an implementation, `/review` organizes findings against the diff. For a paper result, `reproduce` freezes the target first and returns one of five verdicts. ## Audit sources diff --git a/src/content/openscience/skills.mdx b/src/content/openscience/skills.mdx index dbdb20b..6645745 100644 --- a/src/content/openscience/skills.mdx +++ b/src/content/openscience/skills.mdx @@ -5,7 +5,9 @@ description: "Use reusable research procedures and add your own." A skill is a set of instructions and supporting files for a particular workflow. OpenScience loads relevant skills while working, or you can select one explicitly. -The bundled library covers biology, chemistry, physics, machine learning, data engineering, scientific writing, and visualization. Browse the [skill directory](/openscience/skill-library) or your installed version: +The library has two tiers. The **core** skills are the research procedures the agent always has on its index: research lookup, literature review, brainstorming, hypotheses, reproduce, autoresearch, compute, delegation, figures, schematics, paper writing (general and ML), citations, peer review, and sources. Their names and one-line summaries are in every Research request, and the agent loads one when the task matches. Everything else, roughly 340 skills covering biology, chemistry, physics, machine learning, data engineering, cloud GPU providers, scientific databases and documents, is the **library**: found by search, by category, or by exact name when the core index points at it (cloud providers and databases are listed there by name). + +Browse the [skill directory](/openscience/skill-library) or your installed version: ```bash openscience skill list --all @@ -19,7 +21,7 @@ Use the directory to discover a procedure, then check the entry available in you ## Find and use a skill -Open **Customize → Skills** and search by task or subject. Enable the skills you want available. In a conversation, type `/` and search the skill picker, or ask for the procedure in your request. +Open **Customize → Skills**. The catalog is organised the way the agent uses it: **Core** first, in workflow order; **Personal** for the skills you wrote, installed or keep in the project; the **Library** as shelves by subject, each folded until you open it, with Activate all / Turn off all per shelf; and **Sources**, every directory feeding the catalog and any name that lost a collision. The views at the top (All, Core, Library, Personal, Off) narrow the list; search is one flat list across everything. In a conversation, type `/` for the same tiers, or ask for the procedure in your request. ```text Use the appropriate single-cell analysis skill to inspect this dataset. @@ -31,7 +33,7 @@ A skill supplies guidance. It does not guarantee that every referenced package, OpenScience searches the enabled library when it does not know an exact skill name. Search results are suggestions; instructions load only after selecting an available name. If a request includes both an unavailable name and a search query, OpenScience uses the query to find candidates instead of loading a guessed substitute. -Choose **Browse all skills** in the conversation picker to open the searchable library. The list scrolls independently of the search and count controls. Selecting a skill prepares its slash command in the composer; it does not send your request. +The `/` menu opens on Core, then pinned skills, the session actions, and the whole library by subject; typing filters all of it, and a library skill shows its subject on the right. Selecting a skill prepares its slash command in the composer; it does not send your request. Pin a skill in Customize → Skills to keep it near the top of the menu. A successful tool load appears in the conversation as **Loaded skill: name**, even when reasoning and activity are collapsed. Expand it to inspect the saved instructions, then **Load details** for the source and instruction hash. Searches and failed loads are labeled separately. @@ -80,6 +82,20 @@ Before model fitting: Use `openscience skill edit leakage-checks` to revise it. `validate --strict` also fails on warnings. +## Register a local skill directory + +A team pack, a vendor's collection or an air-gapped mirror can join the library without editing a config file or restarting. In **Customize → Skills**, choose **Add skill → Add a local folder**, enter the path and whether to keep it always (your config), for this project (the project config) or until the server restarts; the folder then appears under Sources with a remove control. The same is available through the API and SDK; the skills are scanned at once, nested category folders included: + +```bash +curl -X POST http://127.0.0.1:4096/settings/skills/paths \ + -H 'content-type: application/json' \ + -d '{"path": "/data/team-skills", "persist": "global"}' +``` + +`persist` writes the absolute path to `skills.paths` in the global or the project `openscience.json` so it survives a restart; without it the root lives for this project's server process only. A missing or empty directory is rejected, and a directory that is already a root is refused rather than loaded twice. `GET /settings/skills/paths` lists every root feeding the catalog (bundled, project, user, installed, config, runtime) with the skills it won and the ones it lost to a same-named skill elsewhere; a skill that shadows another carries `shadows` with the losing paths, so a local edit that had no effect is explained. `DELETE /settings/skills/paths?path=…` removes a root, `POST /settings/skills/reload` rescans after files changed outside the app, and `GET /skill/{name}/content` returns a skill's instructions for clients without filesystem access. + +Custom roots load with project precedence: a same-named skill in a registered directory wins over the bundled and personal copies. + ## Use project skills Add a skill under `.openscience/skills//SKILL.md`, or configure additional folders: diff --git a/src/content/openscience/slash-commands.mdx b/src/content/openscience/slash-commands.mdx index 9c7ef7c..2442509 100644 --- a/src/content/openscience/slash-commands.mdx +++ b/src/content/openscience/slash-commands.mdx @@ -3,7 +3,7 @@ title: "Slash commands" description: "Use conversation controls and define reusable project requests." --- -Type `/` in the composer to search commands and enabled skills. The picker reflects what is available in the current project. +Type `/` in the composer. The menu opens on the **Core** toolkit: `/plan`, `/goal`, the core research skills in workflow order (lookup, literature review, brainstorming, hypotheses, reproduce, autoresearch, compute, delegation, figures, schematics, paper writing, citations, peer review, sources) and `/compact`. Pinned skills follow, then the **Session** actions, then the whole skill library by subject. Typing filters everything at once; a library skill shows its subject on the right. ## Conversation controls @@ -11,17 +11,16 @@ Type `/` in the composer to search commands and enabled skills. The picker refle | --- | --- | | `/plan [objective]` | Plan the work before execution. | | `/goal [objective]` | Set an objective to pursue across steps. | -| `/status` | Show current session progress. | -| `/context` | Inspect conversation context usage. | | `/compact [focus]` | Summarize earlier conversation to free context. | -| `/undo` | Revert the latest supported turn after it finishes. | -| `/redo` | Restore reverted work. | -| `/stop` | Stop active work in the session. | +| `/stop` | Stop active work in the session (offered while a turn runs). | | `/checkpoint [label]` | Save a recovery point. | | `/handoff [path]` | Save a continuation note, then compact. | -| `/init` | Create or update project instructions. | +| `/init [notes]` | Write the project's `AGENTS.md`: research question, data locations, conventions, deliverables. | +| `/review [focus]` | Referee the current deliverables with the peer-review skill; blocking issues first. | +| `/reproduce [claim]` | Reproduce a stated result with the reproduce skill, deviations recorded. | +| `/literature [question]` | A focused literature review: two or three searches, the closest papers read. | -Some workflow entries are surfaced as skills or context-sensitive actions. Search by name, and enable the relevant skill if it is not offered. +Session state, context usage, and undo live in the workspace itself: the token counter in the session header shows context usage, and **Undo from here** on a finished response reverts a turn. Compaction summarizes conversation history; it is not a backup of project files. Save important methods and results as files before starting a different task. diff --git a/src/content/openscience/source-types.mdx b/src/content/openscience/source-types.mdx index 02688b0..6a8041e 100644 --- a/src/content/openscience/source-types.mdx +++ b/src/content/openscience/source-types.mdx @@ -38,12 +38,26 @@ Use [Reading and extracting documents](/openscience/documents) for extraction, a | CSV, TSV | Explore rows, columns, missing values, and numeric distributions. | | JSON arrays, JSONL, NDJSON | Inspect record-oriented data in the table explorer. Other JSON opens as source. | | Python, R, Julia, and other source files | Read, edit, and run with the relevant available language tools. | -| Jupyter notebooks | Inspect notebook content and saved outputs; ask to reproduce execution and dependencies separately. | +| Jupyter notebooks (`.ipynb`) | Preview Markdown and code cells with saved text, images, tables, and errors; use Edit for JSON source. | +| R Markdown and Quarto (`.Rmd`, `.qmd`) | Preview prose and fenced code chunks, including referenced figures; use Edit for source. | | YAML, TOML, XML, and text configuration | Inspect and edit source with the schema or application requirements in mind. | | Excel or another application-specific format | Keep the original and use available analysis software to read or convert it. Native spreadsheet editing is not the table preview's role. | Specify delimiters, encoding, sheet names, dates, and missing-value markers when known. See [Tables and datasets](/openscience/tables). +In a research session, use **Run** on a Python or R cell to execute it in that +session's local kernel. Cells share the corresponding runtime's variables; install +the required interpreter and dependencies first. Project execution permissions still +apply. Opening a document never executes code. New outputs are labelled **Run output · +not saved** and remain in that preview; editing and saving the source is separate. +Use **Compute** to inspect or interrupt the runtime. + +The document preview shows Jupyter v4 saved outputs and renders Markdown with code +chunks. It does not run a full Quarto/knitr build, evaluate inline expressions, or +invent outputs that are absent from an R Markdown or Quarto source file. For those +formats, existing figures referenced in Markdown render in place. Other chunk +languages remain visible with execution marked unavailable. + ## Scientific formats | Material | Recognized formats or views | diff --git a/src/content/openscience/team-workflows.mdx b/src/content/openscience/team-workflows.mdx index 4a68155..ffc971e 100644 --- a/src/content/openscience/team-workflows.mdx +++ b/src/content/openscience/team-workflows.mdx @@ -5,6 +5,8 @@ description: "Package files, instructions, and results so another person can con OpenScience projects can produce a self-contained research handoff: inputs the recipient may access, scripts, results, instructions, and a clear account of what remains. A shared funding workspace and a shared research folder are different things. +For shared billing, members, and workspace keys, use the [account workspace guides](https://docs.syntheticsciences.ai/#/account/workspaces). Private Graphs in the dashboard are separate from local OpenScience projects; see [Graphs](https://docs.syntheticsciences.ai/#/account/graphs). The retired Atlas package is not required to use OpenScience. + ## Prepare a handoff package ```text diff --git a/src/content/openscience/tool-catalog.mdx b/src/content/openscience/tool-catalog.mdx index f05c769..bb9ba77 100644 --- a/src/content/openscience/tool-catalog.mdx +++ b/src/content/openscience/tool-catalog.mdx @@ -134,7 +134,7 @@ Protein language-model embeddings and sequence representations. multiple-sequence-alignment search. -**How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials). +**How to use:** An NVIDIA BioNeMo NIM. Connect your NVIDIA API key, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials) · [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). [Documentation and source](https://docs.api.nvidia.com/nim/reference/colabfold-msa-search-infer) · Catalog identifier: `msa-search` @@ -160,7 +160,7 @@ Machine-learning components for molecular and materials workflows. molecular generation. -**How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials). +**How to use:** An NVIDIA BioNeMo NIM. Connect your NVIDIA API key, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials) · [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). [Documentation and source](https://docs.api.nvidia.com/nim/reference/nvidia-genmol-infer) · Catalog identifier: `genmol` @@ -176,7 +176,7 @@ Molecular-mass and elemental-composition calculations. molecule generation and optimization. -**How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials). +**How to use:** An NVIDIA BioNeMo NIM. Connect your NVIDIA API key, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials) · [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). [Documentation and source](https://docs.api.nvidia.com/nim/reference/nvidia-molmim-infer) · Catalog identifier: `molmim` @@ -236,7 +236,7 @@ Molecular docking and virtual-screening command-line workflows. protein-ligand pose generation. -**How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials). +**How to use:** An NVIDIA BioNeMo NIM. Connect your NVIDIA API key, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials) · [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). [Documentation and source](https://docs.api.nvidia.com/nim/reference/mit-diffdock-infer) · Catalog identifier: `diffdock` @@ -272,7 +272,7 @@ Question answering and evidence synthesis over scientific papers. DNA sequence generation. -**How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials). +**How to use:** An NVIDIA BioNeMo NIM. Connect your NVIDIA API key, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials) · [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). [Documentation and source](https://docs.api.nvidia.com/nim/reference/arc-evo2-40b-infer) · Catalog identifier: `evo2` @@ -326,7 +326,7 @@ Materials structures, transformations, and analysis. structure-conditioned protein sequence design. -**How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials). +**How to use:** An NVIDIA BioNeMo NIM. Connect your NVIDIA API key, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials) · [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). [Documentation and source](https://docs.api.nvidia.com/nim/reference/ipd-proteinmpnn-infer) · Catalog identifier: `proteinmpnn` @@ -334,7 +334,7 @@ structure-conditioned protein sequence design. protein backbone generation. -**How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials). +**How to use:** An NVIDIA BioNeMo NIM. Connect your NVIDIA API key, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials) · [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). [Documentation and source](https://docs.api.nvidia.com/nim/reference/ipd-rfdiffusion-infer) · Catalog identifier: `rfdiffusion` @@ -418,7 +418,7 @@ Multimeric protein structure prediction with AlphaFold model weights and databas biomolecular structure and affinity prediction. -**How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials). +**How to use:** An NVIDIA BioNeMo NIM. Connect your NVIDIA API key, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials) · [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). [Documentation and source](https://docs.api.nvidia.com/nim/reference/mit-boltz2-infer) · Catalog identifier: `boltz2` @@ -450,7 +450,7 @@ Crystallographic structure and reflection data handling. monomer structure prediction from MSA and templates. -**How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials). +**How to use:** An NVIDIA BioNeMo NIM. Connect your NVIDIA API key, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials) · [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). [Documentation and source](https://docs.api.nvidia.com/nim/reference/openfold-openfold2-infer) · Catalog identifier: `openfold2` @@ -458,7 +458,7 @@ monomer structure prediction from MSA and templates. multimolecule structure prediction. -**How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials). +**How to use:** An NVIDIA BioNeMo NIM. Connect your NVIDIA API key, check accepted inputs and cost, then try a small case. [Connection guide](/openscience/service-credentials) · [BioNeMo Agent Toolkit](https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit). [Documentation and source](https://docs.api.nvidia.com/nim/reference/openfold-openfold3-infer) · Catalog identifier: `openfold3` diff --git a/src/content/openscience/troubleshooting.mdx b/src/content/openscience/troubleshooting.mdx index ceee00d..ffd72b9 100644 --- a/src/content/openscience/troubleshooting.mdx +++ b/src/content/openscience/troubleshooting.mdx @@ -50,7 +50,13 @@ A pending reservation can reduce available funds before the final charge appears ## A response is slow or times out -Check whether the app is connecting, waiting for output, receiving output, or running a tool. A wait before the first response can include connection and service processing time. +The running header shows **Thinking** or the active tool, with elapsed time. +Hover over it for connection and provider details. A wait before the first +response can include connection and service processing time. + +Inference and Ace credential requests use fresh connections to avoid stale +connection reuse in the bundled runtime. This prevents one source of long +connection waits; it does not shorten a model's reasoning or an upstream queue. Start with a short request and verify the selected model. For a self-hosted model, check server load, memory, context size, and whether it can complete a request directly. @@ -69,10 +75,18 @@ For Ollama, start `ollama serve` if needed. For LM Studio, start its local serve If a `--bare` request works but research tasks fail, verify tool calling and reduce the input or context size. See [Local models](/openscience/local-models). +## Updating reports that OpenScience could not quit safely + +Finish active sessions and compute jobs, then retry the verified update. The desktop waits for all project runtimes to release their processes before it exits; the reported error identifies a failed disposal. It does not force an update over active work. A completed setup stays complete after an update, even if the onboarding flow has changed. An explicit setup reset still opens onboarding. + ## Files are missing or the wrong copy opens Confirm that you opened the intended project. In Files, check **Project files** and **Session scratch** separately. Read the location shown in the preview. +Local result links using `file:` or `sandbox:` open in Files. These prefixes do +not grant access to a folder: the server still checks the current session's +file permissions. + For protected folders on macOS, grant the folder access the operating system requests to the app or terminal you are using, then reopen the folder. A project path must exist and be accessible on the machine running OpenScience. Use [Files and storage](/openscience/files) for data locations and backups. @@ -83,6 +97,12 @@ Open **Customize → Tools** and **Customize → Compute**. Complete the relevan A skill's presence does not mean its dependencies are installed. A saved service key does not mean your account has access to every model or resource. Preserve the reported error and job identifier instead of repeatedly starting the same job. +## Python or R repair reports a Windows file lock + +Update OpenScience, then retry **Set up or repair** in **Customize → Compute**. Repair rechecks both starters, and setup waits briefly for temporary Windows file locks to clear. A starter can show **Ready** while saving the setup status fails: the label reflects whether its interpreter runs. + +If `EPERM`, `EACCES`, or `EBUSY` persists, finish running Python or R work, close other OpenScience instances, and reopen the app before retrying. Keep the existing data folder. Add the full error text, including both rename paths, your Windows and OpenScience versions, and whether Python or R execution also fails to [issue #714](https://github.com/synthetic-sciences/openscience/issues/714). + ## A connector will not connect In **Customize → Connectors**, check whether it is saved but off, awaiting authorization, or reporting an error. diff --git a/src/content/openscience/usage.mdx b/src/content/openscience/usage.mdx new file mode 100644 index 0000000..d0a0ec0 --- /dev/null +++ b/src/content/openscience/usage.mdx @@ -0,0 +1,53 @@ +--- +title: "Usage reports and CSV exports" +description: "Filter activity by source, model, and date, and distinguish Wallet charges from local estimates." +--- + +Open **Customize → Usage** to review model activity. Choose the source first: the Managed report and the reports from saved conversations have different scopes. + +## Choose a source + +| Source | What the report includes | Cost basis | +| --- | --- | --- | +| Managed | Server-recorded usage available to the connected account and funding workspace. | Wallet charges. | +| API keys | Provider-key and custom-route activity in saved conversations on this device, across projects. | Estimates; the provider bills you directly. | +| Local models | Local model activity saved on this device. | No Ace model charge; hardware costs are not included. | +| Subscriptions | ChatGPT and other subscription activity saved on this device. | Subscription fees are not included. | +| Unclassified | Saved activity whose funding route could not be identified. | Do not infer a Wallet charge from an unclassified row. | + +Managed usage requires a connected account. Previously saved API-key and local activity can be viewed while signed out. A device report is not a complete history of work performed on other machines. Deleted conversations are excluded and inherited fork history is not counted twice. Older saved activity without a known route appears under Unclassified, including any managed calls that cannot be classified. + +## Filter the report + +1. Select **Last 7 days**, **Last 30 days**, **Last 90 days**, or **Custom dates**. +2. Set **From** and **To** when you need a particular range. Both dates are inclusive and use UTC; a range can cover at most 366 days. +3. Choose **All models** or a single model. +4. Select **Tokens**, **Cost**, or **Requests** in **Daily activity**. Select or focus a day to inspect its totals. + +The summary shows cost, tokens, requests, and cached input. **By model** summarizes the same filtered records. **Refresh** reloads the report. A loading or connection error is not a confirmed zero-usage result. + +## Export the matching records + +Select **Export CSV** below the report. It exports the selected source, dates, and model filter as daily model/provider totals, including: + +- UTC date, provider, model, route, and request count. +- Input, output, reasoning, cache-read, cache-write, and total tokens. +- USD cost and its cost basis: **Wallet charge** or **Estimate**. + +Output tokens already include reported reasoning; do not add reasoning again. Cached-token fields explain the breakdown, rather than representing extra requests. A small positive cost can appear below one cent; do not round each row to dollars and cents before summing an export. + +The export is an activity report, not a payment invoice. It contains aggregate records, not prompts, complete responses, or project files. + +## Compare with dashboard usage + +The [dashboard Usage page](https://app.syntheticsciences.ai/usage) also supports date and model filters and CSV export. Its account view separates managed usage from reported user-owned routes. Those user-owned records depend on what has reached the account; they need not match a device with unshared local history. + +Workspace usage respects member permissions. Owners and members with usage-view permission can see workspace totals; other members see their own workspace usage. Dashboard CSV exports cover matching daily model/endpoint totals independently of the recent-request list's 50-row limit. + +## Reconcile an amount + +Use **Wallet** for settled managed charges and your provider's billing for direct usage. Card payments add purchased funds and can include a separately disclosed processing fee; they are not the same thing as model spend. Temporary reservations, unsettled requests, different date boundaries, and different account scopes can also explain a mismatch. + +For a single conversation, open its context indicator or run `openscience stats` for local session summaries. These views describe saved research activity and may have a different scope from account reports. If a discrepancy remains, retain the date range, funding workspace, model, request identifier, and relevant CSV rows for support. + +See [Pricing and usage](/openscience/pricing) for rates, reservations, and spending controls, and [Privacy and data](/openscience/privacy) for trace sharing. diff --git a/src/content/openscience/workspace.mdx b/src/content/openscience/workspace.mdx index 08107e7..264b25a 100644 --- a/src/content/openscience/workspace.mdx +++ b/src/content/openscience/workspace.mdx @@ -44,9 +44,9 @@ Only refer to material you have permission to use. For large files, first ask fo ## Follow progress and steer the task -The conversation shows the activity and tool results supplied during the run. Open an individual tool result when you need its inputs or output. +The conversation shows the agent's prose in bright text and everything it did to get there in grey beneath one header per turn: thoughts (with their text when the provider shares it), files read, searches, commands, edits, delegations and questions, in order. While the turn runs the header names the call in flight ("Reading study.json") and the list is open; when it finishes the header reads "Worked for 46m 29s" and folds the list, leaving the answer, any failed call and any question that still needs you. Open an individual row when you need a tool's inputs or output. -You can queue follow-up prompts while a response is running. Stop the current response when you need to change direction immediately. Inspect any files already written before asking it to retry or redo the work. +You can send follow-up prompts while a response is running: they join the current turn and the agent answers them in order. Use the **Stop** button or Escape when you need to change direction immediately. Inspect any files already written before asking it to retry or redo the work. Use [Research controls](/openscience/agents) to choose planning, research effort, delegation, and when the agent asks for your input. @@ -60,7 +60,7 @@ Ask for a text explanation alongside a visual result: what was measured, what th ## Undo and restore -After a response finishes, use **Undo from here** or `/undo` to return to an earlier point. Review the confirmation, which identifies affected work and file changes. A restore action is available for reverted work. +After a response finishes, use **Undo from here** to return to an earlier point. Review the confirmation, which identifies affected work and file changes. A restore action is available for reverted work. Undo is useful for trying a different analysis path. It does not reverse external payments, messages, or changes in a connected service. Use version control or backups for files you need to retain independently of conversation history. @@ -68,6 +68,7 @@ Undo is useful for trying a different analysis path. It does not reverse externa Open **Customize** to manage: +- **Workspaces** for each project's folders, read/write access, and default working location. - **Models** and **Local models** for model access. - **Skills** for reusable instructions. - **Tools** for scientific capability availability. @@ -106,3 +107,23 @@ See [Sessions](/openscience/sessions) for continuing, exporting, and importing c - [Saved Results](/openscience/results): retain verified outputs, download, rename, and recover from Trash. - [Context and handoffs](/openscience/context): compact long work and prepare a continuation. - [Keyboard shortcuts](/openscience/keyboard-shortcuts) and [Preferences](/openscience/preferences): navigate and configure the interface. + +## Usage + +Open **Customize → Usage**, directly below Ace, to see activity by source. +**Managed** shows your confirmed Wallet charges in the selected funding workspace +across devices. **API keys**, **Local models**, and **Subscriptions** show activity +from saved conversations on this device, across projects. API-key costs are +estimates; subscription fees and local hardware costs are not included. + +Choose 7, 30, or 90 days, or enter custom **From** and **To** dates (up to 366 days, +inclusive, in UTC). Filter by model and select tokens, cost, or requests in the +daily chart. **Export CSV** at the bottom downloads daily model totals for the +selected source, dates, and model, including token details and USD costs. + +New requests retain the route used at the time of the call. Older saved activity +without that information appears under **Unclassified**; it may include managed +calls and is kept separate from confirmed charges. Deleted conversations are not +part of device usage, and inherited fork history is not counted twice. + +See [Usage reports and CSV exports](/openscience/usage) for reconciliation and report scope. diff --git a/src/navigation.ts b/src/navigation.ts new file mode 100644 index 0000000..e03bcf9 --- /dev/null +++ b/src/navigation.ts @@ -0,0 +1,118 @@ +export type SectionKey = "openscience" | "account"; +export type Route = { section: SectionKey; path: string; anchor?: string }; + +export const aliases: Record = { + "first-session": "sessions", + "sub-agents": "agents", + "web-ui": "workspace", + "server-mode": "workspace", + "cli-runtime": "commands", + "feature-map": "commands", + codex: "models", + credentials: "ace", + connect: "ace", + gateway: "ace", + atlas: "ace", + security: "permissions", + sandbox: "permissions", + artifacts: "results", + "scientific-data": "databases", +}; + +export const atlasAliases: Record = { + index: { section: "account", path: "compatibility" }, + installation: { section: "account", path: "quickstart" }, + quickstart: { section: "account", path: "graphs" }, + "graph-model": { section: "account", path: "graphs" }, + authentication: { section: "account", path: "authentication" }, + "api-keys": { section: "account", path: "api-keys" }, + billing: { section: "account", path: "billing" }, + "research-loop": { section: "openscience", path: "experiment-tracking" }, + runs: { section: "openscience", path: "experiment-tracking" }, + optimize: { section: "openscience", path: "autoresearch" }, + reproduction: { section: "openscience", path: "reproduction" }, + evidence: { section: "account", path: "evidence" }, + forking: { section: "account", path: "evidence" }, + "web-views": { section: "account", path: "graphs" }, + skills: { section: "openscience", path: "skills" }, + "onboard-agent": { section: "account", path: "compatibility" }, + "cli-overview": { section: "account", path: "compatibility" }, + commands: { section: "account", path: "compatibility" }, + "rest-api": { section: "account", path: "api" }, + "agent-onboarding": { section: "account", path: "compatibility" }, + "auth-config": { section: "account", path: "authentication" }, + "cli-runtime": { section: "account", path: "compatibility" }, + "feature-map": { section: "account", path: "compatibility" }, + "api-reference/introduction": { section: "account", path: "api" }, + "api-reference/atlas-rest": { section: "account", path: "api" }, + "first-graph": { section: "account", path: "graphs" }, + graph: { section: "account", path: "graphs" }, + "artifacts-files": { section: "account", path: "evidence" }, + "exports-imports": { section: "account", path: "evidence" }, + safety: { section: "account", path: "compatibility" }, +}; + +function decode(value: string): string { + try { + return decodeURIComponent(value); + } catch { + return value; + } +} + +export function slug(value: string): string { + return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""); +} + +export function parseRoute(hash: string, legacyProduct = "cli"): Route { + const raw = hash.replace(/^#?\/?/, ""); + const split = raw.indexOf("#"); + const location = decode(split < 0 ? raw : raw.slice(0, split)).replace(/\/$/, ""); + const anchor = split < 0 ? undefined : decode(raw.slice(split + 1)) || undefined; + const segments = location.split("/"); + const section = segments[0]; + const path = segments.slice(1).join("/") || "index"; + if (["atlas", "graphs", "getting-started"].includes(section)) { + return { ...(atlasAliases[path] ?? { section: "account", path }), ...(anchor ? { anchor } : {}) }; + } + if (section === "account") return { section, path, ...(anchor ? { anchor } : {}) }; + if (["openscience", "agent-cli", "cli"].includes(section)) { + if (path === "agent-onboarding") return { section: "account", path: "compatibility" }; + return { section: "openscience", path: aliases[path] ?? path, ...(anchor ? { anchor } : {}) }; + } + if (legacyProduct === "atlas" && location && atlasAliases[location]) { + return { ...atlasAliases[location], ...(anchor ? { anchor } : {}) }; + } + if (location === "agent-onboarding") return { section: "account", path: "compatibility" }; + if (["auth-config", "api-reference/introduction", "api-reference/atlas-rest", "first-graph", "graph", "artifacts-files", "exports-imports", "safety"].includes(location)) { + return { ...atlasAliases[location], ...(anchor ? { anchor } : {}) }; + } + return { section: "openscience", path: aliases[location] ?? (location || "index"), ...(anchor ? { anchor } : {}) }; +} + +export function pageHref(section: SectionKey, path: string, anchor?: string): string { + return `#/${section}/${path}${anchor ? "#" + encodeURIComponent(anchor) : ""}`; +} + +export function resolveLink(href: string | undefined, current: Route): string | undefined { + if (!href || /^(https?:|mailto:|tel:)/.test(href)) return href; + if (href.startsWith("#") && !href.startsWith("#/")) return pageHref(current.section, current.path, decode(href.slice(1))); + const raw = href.replace(/^#?\/?/, ""); + const qualified = /^(openscience|account|atlas|graphs|getting-started|agent-cli|cli)(\/|$)/.test(raw); + const route = parseRoute(qualified ? raw : `${current.section}/${raw}`); + return pageHref(route.section, route.path.replace(/\.(mdx|md)$/, ""), route.anchor); +} + +export function headings(markdown: string, depth = 2): string[] { + const state = { fence: "" }; + return markdown.split("\n").flatMap((line) => { + const fence = line.match(/^\s*([\x60]{3,}|~{3,})/); + if (fence) { + if (!state.fence) state.fence = fence[1]; + else if (fence[1][0] === state.fence[0] && fence[1].length >= state.fence.length) state.fence = ""; + return []; + } + const heading = line.match(/^(#{2,3}) (.+)$/); + return !state.fence && heading && heading[1].length <= depth ? [heading[2].trim()] : []; + }); +} diff --git a/test/navigation.test.mjs b/test/navigation.test.mjs new file mode 100644 index 0000000..75fb4e7 --- /dev/null +++ b/test/navigation.test.mjs @@ -0,0 +1,37 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { aliases, atlasAliases, headings, parseRoute, resolveLink, pageHref } from "../src/navigation.ts"; + +test("section links retain their page and survive a canonical round trip", () => { + const route = parseRoute("#/openscience/usage#export-the-matching-records"); + assert.deepEqual(route, { section: "openscience", path: "usage", anchor: "export-the-matching-records" }); + assert.equal(pageHref(route.section, route.path, route.anchor), "#/openscience/usage#export-the-matching-records"); + assert.equal(resolveLink("#rates", { section: "account", path: "billing" }), "#/account/billing#rates"); + assert.equal(resolveLink("/openscience/usage#choose-a-source", route), "#/openscience/usage#choose-a-source"); +}); + +test("legacy product and page URLs resolve without reviving retired instructions", () => { + for (const [old, path] of Object.entries(aliases)) { + for (const section of ["openscience", "agent-cli", "cli"]) assert.deepEqual(parseRoute(`#/${section}/${old}`), { section: "openscience", path }); + } + for (const [old, target] of Object.entries(atlasAliases)) { + for (const section of ["atlas", "graphs", "getting-started"]) assert.deepEqual(parseRoute(`#/${section}/${old}`), target); + assert.deepEqual(parseRoute(`#/${old}`, "atlas"), target); + } +}); + +test("unknown and malformed URLs stay recoverable", () => { + assert.deepEqual(parseRoute("#/api-reference/atlas-rest"), { section: "account", path: "api" }); + assert.deepEqual(parseRoute("#/first-graph"), { section: "account", path: "graphs" }); + assert.deepEqual(parseRoute("#/account/missing"), { section: "account", path: "missing" }); + assert.deepEqual(parseRoute("#/openscience/%E0%A4%A"), { section: "openscience", path: "%E0%A4%A" }); + assert.deepEqual(parseRoute(""), { section: "openscience", path: "index" }); + assert.equal(resolveLink("https://example.com/#part", { section: "account", path: "index" }), "https://example.com/#part"); + assert.equal(resolveLink("/billing", { section: "account", path: "index" }), "#/account/billing"); +}); + +test("table of contents ignores examples and supports third-level targets", () => { + const source = "## Real\n```markdown\n## Example\n```\n### Detail\n~~~text\n### Also an example\n~~~\n## End"; + assert.deepEqual(headings(source), ["Real", "End"]); + assert.deepEqual(headings(source, 3), ["Real", "Detail", "End"]); +});