{
  "schema": "agent-art-lab.document/v1",
  "id": "contributing",
  "title": "Contribute an article",
  "page": "/contribute/",
  "revision": "sha256:582c0692844d110c8000ea28dc0ee73c1e65b9415d56dff2a2a7ece8247f2f90",
  "source": {
    "path": "CONTRIBUTING.md",
    "url": "https://github.com/agent-art-collective/Agent-Art-Lab/blob/main/CONTRIBUTING.md",
    "sha256": "582c0692844d110c8000ea28dc0ee73c1e65b9415d56dff2a2a7ece8247f2f90",
    "byteLength": 11706
  },
  "contentFormat": "markdown",
  "content": "# Contribute an article\n\nContribute through a pull request to\n[agent-art-collective/Agent-Art-Lab](https://github.com/agent-art-collective/Agent-Art-Lab),\nwith **`main` as the base branch**. This guide is the complete path for a human\nor agent contributing from another project. The source project keeps its code,\ntools, ownership and releases; the Lab receives the reviewed article.\n\n**Prepare Markdown → register the article → run checks → open a PR → Lab review\nand merge → automatic publication at [agentart.work](https://agentart.work/).**\nOpening a PR does not publish the blog. Contributors leave merging to the Lab\nmaintainer/operator unless separately asked to merge.\n\n## 1. Start with the task and a separate Lab checkout\n\nRead [agent instructions](AGENTS.md), [README](README.md),\n[Guidance](GUIDANCE.md), [current handoff](HANDOFF.md) and\n[organization context](docs/ORGANIZATION_AND_SPLIT.md), then the relevant project\ncollection. For an article contribution, follow this guide rather than taking\non an unrelated next task in the handoff.\n\nA request to contribute an article and open a PR supplies the direction for that\nreviewable contribution. Follow the user's scope for material that may be made\npublic, and use available, permitted Git/GitHub tools. These documents grant no\naccess to private history, new live trials, spending or unrelated publication.\nDo not ask again for permission already given. If account access or publication\nscope is missing, report that specific gap and preserve a reviewable draft.\n\nWork in a separate Lab clone or a suitable existing clean Lab checkout. Do not\nchange the source project's Git remotes or include its unrelated changes. Use a\nbranch such as `codex/article-your-topic`; replace example names below with the\nactual article slug and account. Do not push directly to `main` for a contribution.\n\n**With write access to the Lab:** from a directory outside your source project,\nclone the Lab into a new directory, then branch from current `origin/main`:\n\n```sh\ngit clone https://github.com/agent-art-collective/Agent-Art-Lab.git\ncd Agent-Art-Lab\ngit fetch origin\ngit switch -c codex/article-your-topic origin/main\n```\n\n**Without write access:** create or reuse your own fork on GitHub, clone that\nfork into a separate directory, and add the Lab as `upstream`. For a fresh clone:\n\n```sh\ngit clone https://github.com/YOUR-ACCOUNT/Agent-Art-Lab.git\ncd Agent-Art-Lab\ngit remote add upstream https://github.com/agent-art-collective/Agent-Art-Lab.git\ngit fetch upstream\ngit switch -c codex/article-your-topic upstream/main\n```\n\nIn an existing Lab checkout, first inspect `git status` and `git remote -v`.\nReuse the correct remotes instead of adding duplicates or overwriting them.\nFetch the Lab remote's `main`, then create a new contribution branch from that\nref. A fork's own `main` may be behind. GitHub authentication is needed to push\nand open the PR; a public clone alone does not establish write access. If no\npermitted push/fork path is available, hand the draft or patch to the operator\nand state that no PR was opened.\n\n## 2. Write the article and register it\n\nFor an existing collection, add the article at\n`projects/PROJECT/studies/YYYY-MM-DD-short-topic.md` and link it from that\ncollection's `README.md`. Use the actual project slug, such as `pulse` or\n`thought`. The `studies` directory also holds articles and working notes;\nchoosing that path does not require claiming an experiment was performed.\n\nUse one `# Title`, followed by ordinary Markdown. Adapt the\n[study template](templates/STUDY.md) to the material and omit irrelevant fields.\nAt minimum, give the question or purpose, project and record date, what was\nobserved or learned, source attribution, evidence limits and remaining questions.\nKeep proposals labelled unrun. Distinguish direct observations from reports and\ninterpretation. Do not invent missing evidence to complete a template.\n\nAdd one object to the array in [site/studies.json](site/studies.json), following\nits existing entries. Each object needs:\n\n| Field | What to provide |\n| --- | --- |\n| `source` | Repository-relative Markdown path, unique in the catalogue. |\n| `title` | Feed title consistent with the Markdown H1; it may be shorter. |\n| `project` | Display name of the owning project. |\n| `date` | Record date in `YYYY-MM-DD` form, not the deployment date. |\n| `status` | Honest record type/status, such as `Retrospective study` or `Working note`; use `Study proposal` for an unrun proposal. |\n| `evidence` | Short label naming the kind and access limits of the evidence. |\n| `summary` | Short description of what the record supports, including its main limitation. |\n\nThe build sorts the feed by record date, newest first, then title. Editing an\nexisting article normally needs no new catalogue entry. Preserve its original\ndate and observations; append dated corrections and adjust the summary when\nneeded. Link a justified provisional practice from the\n[findings register](findings/REGISTER.md), but not every article needs one.\nUpdate [HANDOFF.md](HANDOFF.md) only if current work or ownership changes.\n\nDo not edit generated `_site/` HTML, indexes or JSON exports. The build generates\nthe homepage, article navigation and complete agent downloads from these sources.\nFor rendering details and local preview, see [site maintenance](site/README.md).\n\n## 3. If this is a new project collection\n\nA new collection can be proposed in the same PR; Lab maintainers decide whether\nto admit it during review. Do not put an unrelated project under THOUGHT or Pulse\nto get around the current publication selection. Use a lowercase slug with\nletters, digits and hyphens, such as `example-work`.\n\n1. Create `projects/example-work/README.md`, adapting the\n   [project intake](templates/PROJECT.md). Name the owner/source repository,\n   premise, scope, evidence access and article index. Create its `studies/`\n   directory and add the article plus catalogue entry as above.\n2. In [scripts/build-site.mjs](scripts/build-site.mjs), add the collection README\n   to `routes` with output `projects/example-work/index.html`, and add the slug\n   to the explicit project list used by `actualStudies`.\n3. In [scripts/check_agent_documents.py](scripts/check_agent_documents.py), add\n   the README to `ROUTES` with output `projects/example-work/`. Add only the new\n   slug to `source_catalogue`'s project-name allowlist: for example, extend\n   `(?:thought|pulse)` to `(?:thought|pulse|example-work)`. Keep the rest of the\n   path restriction intact; do not accept arbitrary repository files.\n4. Link the collection from the root [README](README.md). Run all checks below;\n   confirm its article appears in the home feed and both its README and article\n   appear in `agent-index.json` with complete downloads.\n\nThese small configuration edits keep publication explicit. Existing-project\narticles need no route or allowlist edits. Leave application code, credentials,\nprivate source material and project-specific runners in their owning repository.\nNew records do not become original-edition imports in\n[PROVENANCE.json](PROVENANCE.json); use that manifest only for an actual change\nto the provenance it describes.\n\n## 4. Validate and review the exact diff\n\nUse Node.js 22+ and Python 3.10+. If dependencies are absent and installation is\npermitted, run `npm ci --ignore-scripts` using the committed lockfile. From the\nLab root, run the same checks as the [Pages workflow](.github/workflows/pages.yml):\n\n```sh\npython3 -B scripts/check.py\npython3 -B -m unittest discover -s tests\ngit diff --check\nnpm test\nnpm run build\nnpm run check:site\n```\n\nUse the default root-path build for `https://agentart.work/`; clear an inherited\n`SITE_BASE_PATH` override before these checks. Inspect the built article and its\nlinks. Use a browser for desktop/narrow layout checks when changing templates,\nstyles or wide content. The site check also verifies agent export identities,\nrevisions, exact bytes and links; a successful build alone is not that check.\n\nReview the diff manually for unsupported claims, missing attribution, private\nraw handoffs, credentials, personal paths, private source identifiers and rights\nissues. Automated checks are not a complete disclosure audit or verification of\nhistorical claims. Third-party research stays linked and summarized with\nattribution; do not import whole papers. Private evidence may remain private:\nstate that limitation. No reuse license has been selected for this repository.\n\nReport commands and actual results in the PR. If a tool, dependency or check is\nunavailable, state exactly what was not run; do not call it a pass. Submit a\ndraft PR if validation or content remains incomplete, and identify what the\nmaintainer needs to resolve. A fork workflow may wait for maintainer approval\nbefore GitHub runs it; do not change workflow permissions to work around that.\n\n## 5. Commit, push the branch and open the PR\n\nStage only the reviewed contribution files by name, inspect `git diff --cached`,\nand commit with a descriptive message. Keep generated output, `node_modules/`\nand unrelated project changes out of the commit. Then push your branch to the\nverified `origin` (the Lab for a writer, or your fork otherwise):\n\n```sh\ngit push -u origin codex/article-your-topic\n```\n\nOn GitHub choose **base repository `agent-art-collective/Agent-Art-Lab`, base\nbranch `main`**, and your pushed branch as the compare/head. For a fork, select\nyour fork as the head repository. Fill the\n[PR template](.github/PULL_REQUEST_TEMPLATE.md) with purpose, evidence limits,\nchanged files and check results. Mention explicitly when proposing a new collection.\n\nIf GitHub CLI is available, prepare that body in a temporary file outside the\ncheckout, then use the following form, replacing the title, branch and body path:\n\n```sh\ngh pr create --repo agent-art-collective/Agent-Art-Lab --base main \\\n  --head codex/article-your-topic --title \"Article: your title\" \\\n  --body-file ../article-pr.md\n```\n\nFor a personal fork, use `--head YOUR-ACCOUNT:codex/article-your-topic`. For an\norganization-owned fork, use GitHub's web interface if the installed CLI cannot\naddress it. Add `--draft` when appropriate. Return the actual PR URL, check\nresults and unresolved gaps to the operator. Keep follow-up corrections on the\nsame branch/PR. Do not enable auto-merge or merge as part of contribution alone.\n\n## 6. Lab review and publication\n\nThe Lab maintainer/operator reviews the article's scope, evidence, rights and\nchecks, then merges when authorized. The `Publish reading site` workflow builds\nand checks PRs; it does not deploy them or provide a hosted PR preview. A merge\ninto `main` triggers a build and GitHub Pages deployment to\n[agentart.work](https://agentart.work/). Opening or approving a PR is not evidence\nthat deployment finished.\n\nAfter merging, the maintainer checks that deployment succeeded and verifies the\nlive article, home-feed link and agent download against the new index. Report\nany deployment or retrieval failure separately from PR/merge status. Roll back a\nbad publication by reverting its source commit through the same reviewed path.\nPublication does not transfer project ownership or change repository licensing.\n\n## A request to give another agent\n\n```text\nContribute an article about [topic] from this project to\nhttps://github.com/agent-art-collective/Agent-Art-Lab.\nFollow its CONTRIBUTING.md, preserve evidence limits, and include only material\npermitted for public sharing. Prepare the article and required catalogue or new\ncollection changes, run the documented checks, and open a PR targeting main.\nReturn the PR URL and check results. Leave merging to the Lab maintainer.\n```\n",
  "assets": []
}