openresearchworkspace 0.1.0a1__tar.gz

openresearchworkspace-0.1.0a1/.github/workflows/initialize-project.yml

@@ -0,0 +1,120 @@
+name: Initialize research project
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  contents: write
+  issues: write
+
+concurrency:
+  group: initialize-project-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  initialize:
+    name: Create project structure and metadata
+    if: >-
+      contains(github.event.issue.body, '### Project title') &&
+      contains(github.event.issue.body, '### Ready to initialize') &&
+      github.repository != 'dhuzard/OpenResearchWorkspace'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check who submitted the setup form
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          USER: ${{ github.event.issue.user.login }}
+        run: |
+          permission=$(gh api "repos/$REPO/collaborators/$USER/permission" --jq '.permission')
+          case "$permission" in
+            admin|maintain|write)
+              echo "Setup submitted by authorized repository participant $USER ($permission)."
+              ;;
+            *)
+              echo "::error::Project initialization must be submitted by a repository owner or collaborator with write access."
+              exit 1
+              ;;
+          esac
+
+      - name: Check out project
+        uses: actions/checkout@v4
+
+      - name: Refuse accidental re-initialization
+        shell: bash
+        run: |
+          if [ -f .research/initialized ]; then
+            echo "::error::This project has already been initialized."
+            exit 1
+          fi
+
+      - name: Read and validate setup form
+        id: setup
+        run: python scripts/parse_setup_issue.py
+
+      - name: Create ISA-aligned project files
+        env:
+          ORW_SETUP_JSON: ${{ steps.setup.outputs.setup_payload }}
+          ORW_PROVIDER: github
+          ORW_PROVIDER_USER: ${{ github.event.issue.user.login }}
+        run: python scripts/initialize_project.py
+
+      - name: Commit initialized workspace
+        shell: bash
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add README.md .research studies project-docs references
+          if git diff --cached --quiet; then
+            echo "::error::Initialization produced no changes."
+            exit 1
+          fi
+          git commit -m "Initialize research workspace"
+          git push
+
+      - name: Confirm setup in the form thread
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          REPO: ${{ github.repository }}
+        shell: bash
+        run: |
+          cat > /tmp/orw-success.md <<EOF
+          ✅ **Your OpenResearchWorkspace project is initialized.**
+
+          ORW created your first ISA Study/Assay structure and updated the project metadata and README.
+
+          ➡️ **[Open your initialized workspace](https://github.com/$REPO)**
+
+          This setup form is now complete and will be closed automatically.
+          EOF
+          gh issue comment "$ISSUE_NUMBER" --repo "$REPO" --body-file /tmp/orw-success.md
+          gh issue close "$ISSUE_NUMBER" --repo "$REPO" --reason completed
+
+      - name: Workflow summary
+        run: |
+          echo "## Research workspace initialized" >> "$GITHUB_STEP_SUMMARY"
+          echo "The setup form was validated and the ISA-aligned workspace was created." >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Explain a failed setup
+        if: failure()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          REPO: ${{ github.repository }}
+          RUN_URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        shell: bash
+        run: |
+          cat > /tmp/orw-failure.md <<EOF
+          ❌ **ORW could not finish initialization.**
+
+          The setup form has been left open so you can ask for help or correct the problem.
+
+          Technical details: $RUN_URL
+
+          If you are a beginner, you do not need to understand that log yourself—share the link when asking for help.
+          EOF
+          gh issue comment "$ISSUE_NUMBER" --repo "$REPO" --body-file /tmp/orw-failure.md

openresearchworkspace-0.1.0a1/.github/workflows/release-alpha.yml

@@ -0,0 +1,215 @@
+name: Publish alpha (TestPyPI first)
+on:
+  workflow_dispatch:
+    inputs:
+      phase:
+        description: 'TestPyPI rehearsal, or promote a successful rehearsal to PyPI'
+        required: true
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+      version:
+        description: 'Explicit alpha version'
+        required: true
+        type: string
+        default: '0.1.0a1'
+      rehearsal_run:
+        description: 'Successful TestPyPI run ID (required for PyPI promotion)'
+        type: string
+        default: ''
+      confirmation:
+        description: 'For public promotion enter: publish 0.1.0a1'
+        type: string
+        default: ''
+permissions:
+  contents: read
+  actions: read
+concurrency:
+  group: orw-alpha-${{ inputs.version }}
+  cancel-in-progress: false
+env:
+  VERSION: ${{ inputs.version }}
+  PHASE: ${{ inputs.phase }}
+  REHEARSAL_RUN: ${{ inputs.rehearsal_run }}
+  CONFIRMATION: ${{ inputs.confirmation }}
+  PYTHONUTF8: '1'
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - name: Enforce main, alpha version, environment reviewers and rehearsal provenance
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python scripts/release.py guard
+
+  checks:
+    needs: guard
+    if: inputs.phase == 'testpypi'
+    uses: ./.github/workflows/release-checks.yml
+
+  build:
+    needs: [guard, checks]
+    if: inputs.phase == 'testpypi'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - name: Install build and browser test dependencies
+        run: |
+          python -m pip install . build twine -r browser/requirements-test.txt
+          python -m playwright install --with-deps chromium
+      - name: Real browser acceptance tests
+        run: python -m unittest discover -s browser/tests -v
+      - name: Build and test the immutable candidate
+        run: python scripts/release.py build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: alpha-candidate
+          path: candidate/
+          if-no-files-found: error
+          retention-days: 30
+
+  publish-testpypi:
+    needs: build
+    if: inputs.phase == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      contents: read
+      actions: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          name: alpha-candidate
+          path: candidate/
+      - name: Upload exact candidate to TestPyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: candidate/packages/
+          skip-existing: true
+
+  verify-testpypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          name: alpha-candidate
+          path: candidate/
+      - name: Download actual TestPyPI bytes, verify hashes, install wheel and sdist
+        run: python scripts/release.py registry --index testpypi
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: alpha-verified
+          path: candidate/
+          if-no-files-found: error
+          retention-days: 30
+
+  acquire-verified:
+    needs: guard
+    if: inputs.phase == 'pypi'
+    runs-on: ubuntu-latest
+    outputs:
+      source_sha: ${{ steps.proof.outputs.source_sha }}
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          name: alpha-verified
+          path: candidate/
+          run-id: ${{ inputs.rehearsal_run }}
+          github-token: ${{ github.token }}
+      - name: Verify provenance and TestPyPI again; never rebuild
+        id: proof
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python scripts/release.py promotion
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: alpha-approved
+          path: candidate/
+          if-no-files-found: error
+          retention-days: 30
+
+  publish-pypi:
+    needs: acquire-verified
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      actions: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          name: alpha-approved
+          path: candidate/
+      - name: Upload the exact rehearsed artifacts to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          packages-dir: candidate/packages/
+          skip-existing: true
+
+  verify-pypi:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          name: alpha-approved
+          path: candidate/
+      - name: Verify public index bytes and clean installations
+        run: python scripts/release.py registry --index pypi
+
+  github-prerelease:
+    needs: [verify-pypi, acquire-verified]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      actions: read
+    steps:
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5
+        with:
+          name: alpha-approved
+          path: candidate/
+      - name: Publish matching browser and Python prerelease assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: dhuzard/OpenResearchWorkspace
+          SOURCE_SHA: ${{ needs.acquire-verified.outputs.source_sha }}
+        run: |
+          gh release create "v$VERSION" --target "$SOURCE_SHA" --prerelease \
+            --title "OpenResearchWorkspace $VERSION" \
+            --notes "Evaluation alpha. TestPyPI rehearsal and public package read-back succeeded. Use disposable copies; inspect metadata before sharing. See the release guide and changelog for limitations." \
+            candidate/packages/* candidate/orw-browser-generator-*.zip \
+            candidate/index.html candidate/manifest.json candidate/rehearsal.json

openresearchworkspace-0.1.0a1/.github/workflows/release-checks.yml

@@ -0,0 +1,53 @@
+name: Alpha release checks
+on:
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+permissions:
+  contents: read
+jobs:
+  distributions:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ['3.10', '3.13']
+    runs-on: ${{ matrix.os }}
+    env:
+      PYTHONUTF8: '1'
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: '22'
+      - name: Install build and test dependencies
+        run: python -m pip install . build twine
+      - name: Regression and cross-language tests
+        run: python -m unittest discover -s tests -v
+      - name: Build wheel and source distribution
+        run: python -m build --outdir dist/packages
+      - name: Check package metadata and Markdown
+        run: python -m twine check --strict dist/packages/*
+        shell: bash
+      - name: Test exact artifacts in separate clean environments
+        run: python scripts/test_distributions.py dist/packages --version 0.1.0a1
+      - name: Rebuild standalone browser from source
+        run: python scripts/build_browser.py
+      - name: Exercise the candidate-building path without upload credentials
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.13'
+        run: |
+          python scripts/release.py build --directory dist/release-candidate --version 0.1.0a1
+          python scripts/release.py verify --directory dist/release-candidate --version 0.1.0a1
+      - name: Share non-published review artifacts
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.13'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: alpha-review-artifacts
+          path: dist/release-candidate/
+          if-no-files-found: error
+          retention-days: 14

openresearchworkspace-0.1.0a1/.github/workflows/test-browser.yml

@@ -0,0 +1,68 @@
+name: Browser generator
+
+on:
+  pull_request:
+    paths:
+      - 'browser/**'
+      - 'scripts/build_browser.py'
+      - 'src/orw/**'
+      - 'schema/**'
+      - 'tests/test_browser_contract.py'
+      - 'tests/fixtures/setup/**'
+      - '.github/workflows/test-browser.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'browser/**'
+      - 'scripts/build_browser.py'
+      - 'src/orw/**'
+      - 'schema/**'
+      - 'tests/test_browser_contract.py'
+      - 'tests/fixtures/setup/**'
+      - '.github/workflows/test-browser.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: browser-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  browser:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+      - name: Install test dependencies
+        run: |
+          python -m pip install . -r browser/requirements-test.txt
+          python -m playwright install --with-deps chromium
+      - name: Cross-language contract and ZIP tests
+        run: python -m unittest discover -s tests -p test_browser_contract.py -v
+      - name: Build standalone application
+        run: python scripts/build_browser.py
+      - name: Browser acceptance (HTTP, file, offline, downloads)
+        env:
+          ORW_SCREENSHOT_DIR: dist/browser-evidence
+        run: python -m unittest discover -s browser/tests -v
+      - name: Share tested static build
+        uses: actions/upload-artifact@v4
+        with:
+          name: orw-browser-generator
+          path: dist/browser/index.html
+          if-no-files-found: error
+      - name: Share synthetic test screenshots
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: browser-test-screenshots
+          path: dist/browser-evidence/
+          if-no-files-found: ignore

openresearchworkspace-0.1.0a1/.github/workflows/test-core.yml

@@ -0,0 +1,72 @@
+name: Test ORW core and CLI
+
+on:
+  push:
+    paths:
+      - "src/orw/**"
+      - "tests/**"
+      - "scripts/**"
+      - "schema/**"
+      - "pyproject.toml"
+      - ".github/workflows/test-core.yml"
+  pull_request:
+    paths:
+      - "src/orw/**"
+      - "tests/**"
+      - "scripts/**"
+      - "schema/**"
+      - "pyproject.toml"
+      - ".github/workflows/test-core.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Core, CLI, and installed-command tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install ORW package
+        run: python -m pip install .
+
+      - name: Run unit and contract tests
+        run: python -m unittest discover -s tests -v
+
+      - name: Test installed CLI outside checkout
+        shell: bash
+        run: |
+          workdir="$(mktemp -d)"
+          cd "$workdir"
+
+          orw --version
+          orw init study --config "$GITHUB_WORKSPACE/tests/fixtures/setup/basic.json"
+          orw validate study
+          orw validate study --json > validation.json
+          orw export study --format ro-crate --output crate
+
+          python - <<'PY'
+          import json
+          from pathlib import Path
+
+          payload = json.loads(Path("validation.json").read_text())
+          assert payload["valid"] is True, payload
+          assert payload["issues"] == [], payload
+          assert Path("study/.research/project.yml").is_file()
+
+          crate = json.loads(Path("crate/ro-crate-metadata.json").read_text())
+          assert crate["@context"] == "https://w3id.org/ro/crate/1.3/context"
+          by_id = {entity["@id"]: entity for entity in crate["@graph"]}
+          assert by_id["ro-crate-metadata.json"]["conformsTo"]["@id"] == "https://w3id.org/ro/crate/1.3"
+          assert by_id["./"]["@type"] == "Dataset"
+          assert Path("crate/.research/project.yml").is_file()
+          PY

openresearchworkspace-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.1.0a1 — release candidate; not yet published
+
+### Added
+
+- Provider-neutral workspace generation, CLI initialization and validation, and RO-Crate 1.3 directory export.
+- Standalone browser generator with local ZIP creation and Python/browser contract checks.
+- Wheel/source-distribution smoke tests and a staged TestPyPI → public PyPI publishing workflow using the same verified artifacts.
+- Software version in `src/orw/_version.py`; specification/template versions remain independent.
+
+### Safety fixes
+
+- Normal initialization refuses every nonempty destination, including unmarked scientific projects and existing README files.
+- Explicit template initialization verifies the original placeholder metadata and preserves the previous overview and metadata in `.research/template-*` files.
+- Export source/output trees must be disjoint, even with `--force`.
+- Forced replacement requires a recognized, unchanged ORW export inventory. Added or edited files, symlinks/junctions, and legacy unmarked exports are not deleted.
+- New export is validated in staging before replacement; the previous export is renamed aside and restored if final promotion fails.
+- Open resource directories cannot silently include separately private/restricted/embargoed/unknown resources. Contradictory access declarations fail before copy.
+
+### Limitations
+
+- Evaluation alpha, not a complete OSF replacement or a FAIR certification.
+- Use disposable copies and exclusive access during filesystem mutations; these guards are not a sandbox against malicious concurrent path substitution.
+- Export metadata may contain sensitive names or locations. Inspect before sharing; access labels do not encrypt or control filesystem access.
+- A new output directory is required for exports created before inventory markers were introduced.

openresearchworkspace-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damien Huzard and OpenResearchWorkspace contributors
+
+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.

openresearchworkspace-0.1.0a1/MANIFEST.in

@@ -0,0 +1,15 @@
+include LICENSE README.md CHANGELOG.md pyproject.toml MANIFEST.in
+recursive-include src *.py *.json *.yml
+recursive-include schema *.json
+recursive-include scripts *.py
+recursive-include tests *.py *.json
+recursive-include browser *.html *.css *.js *.py *.txt
+recursive-include docs *.md
+recursive-include .github/workflows *.yml
+prune docs/assets
+prune dist
+prune build
+prune .git
+prune .venv
+prune .orw-playwright-github
+global-exclude __pycache__ *.py[cod] .DS_Store

openresearchworkspace-0.1.0a1/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: openresearchworkspace
+Version: 0.1.0a1
+Summary: Local-first research workspace creation, validation, and RO-Crate export
+Author: OpenResearchWorkspace contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dhuzard/OpenResearchWorkspace
+Project-URL: Documentation, https://github.com/dhuzard/OpenResearchWorkspace/blob/main/docs/cli.md
+Project-URL: Repository, https://github.com/dhuzard/OpenResearchWorkspace
+Project-URL: Issues, https://github.com/dhuzard/OpenResearchWorkspace/issues
+Project-URL: Changelog, https://github.com/dhuzard/OpenResearchWorkspace/blob/main/CHANGELOG.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6.0
+Requires-Dist: jsonschema<5,>=4.22
+Dynamic: license-file
+
+# OpenResearchWorkspace — public alpha
+
+A local-first toolkit for creating, validating, and exporting research workspaces. Git, a hosted forge, and an AI provider are not required. The canonical scientific record is `.research/project.yml`, organized around Investigation, Study, and Assay concepts.
+
+## Install
+
+Once the alpha is published:
+
+```bash
+pipx install openresearchworkspace==0.1.0a1
+```
+
+Alternatively, in a Python 3.10+ virtual environment:
+
+```bash
+python -m pip install openresearchworkspace==0.1.0a1
+```
+
+## Use
+
+```bash
+orw init my-study
+orw validate my-study
+orw validate my-study --json
+orw export my-study --format ro-crate --output my-study-crate
+```
+
+Automated initialization accepts the normalized setup contract through `--config setup.json` or `--config -` for standard input. Normal initialization requires a new or empty destination. Export destinations must be outside the source workspace. `--force` only replaces a previously marked ORW export whose files have not been added, removed, or changed.
+
+## Browser path
+
+The matching standalone HTML generator is distributed separately as a versioned release asset. Open it in a browser, describe the project, review the structure and metadata, and download a workspace ZIP. Python is not required by that browser path. The ZIP is not encrypted and exporting it does not publish anything.
+
+## Alpha boundaries
+
+This release is for evaluation on disposable copies. It is not a complete research-data repository, a security sandbox, or a guarantee of FAIR compliance. Initialization creates one Study and an optional first Assay. Browser editing of existing workspaces, DOI deposition, richer provenance, and agent integrations remain planned.
+
+RO-Crate output is a local package, not a publication. Base checks are bounded to the exporter; a dedicated ORW RO-Crate Profile is not claimed. Metadata and the project README are included, so inspect them for sensitive information before sharing. Only explicitly open local resources are copied; overlapping open/restricted declarations are refused. Metadata access labels are not filesystem permissions or encryption. Mutation operations require exclusive workspace access; concurrent or hostile filesystem mutation is outside the alpha's guarantees.
+
+## Documentation and source
+
+[CLI guide](https://github.com/dhuzard/OpenResearchWorkspace/blob/main/docs/cli.md) · [Browser guide](https://github.com/dhuzard/OpenResearchWorkspace/blob/main/docs/browser-generator.md) · [Release process](https://github.com/dhuzard/OpenResearchWorkspace/blob/main/docs/releases.md) · [Issues](https://github.com/dhuzard/OpenResearchWorkspace/issues)
+
+The software is MIT licensed. Research outputs do not automatically inherit that license. ORW specification and template versions are independent of the software release version.