Artifact asset transfers

[rsgalloway]

This pull request introduces API support for artifact downloads and asset uploads, improves the CLI's handling of result output, and updates documentation to reflect these new workflows and options. The changes add Artifacts and Assets resources to the Python client, implement secure file streaming and upload logic, and clarify CLI output behavior. Documentation is expanded with a new API/file workflow guide and improved references.

API and Client Enhancements:

• Added Artifacts and Assets resources to the Python client, with methods for downloading artifacts to local files (with safe handling, size limits, and redirect support) and uploading assets to graphs. [1] [2] [3]
• Improved internal error handling and response checking for API requests, including credential-safe exceptions and better JSON parsing. [1] [2] [3]

CLI Improvements:

• Changed the execute command to only emit result JSON when explicitly requested with -o/--out or --raw, and clarified the meaning of output options (including support for -o - to print to stdout). [1] [2] [3] [4]
• Updated CLI help and documentation to match the new output behavior and options. [1] [2] [3]

Documentation Updates:

• Added a new docs/api.md guide covering Python API usage for executing graphs, downloading artifacts, and uploading assets, with practical code examples.
• Updated main documentation and usage guides to reference the new API/file workflow documentation and clarify asset and artifact handling. [1] [2] [3]

Testing:

• Added a new test mode for CLI execution output to ensure explicit stdout behavior is covered.

These changes provide a more robust and user-friendly workflow for managing files and results in Subfork, both from the command line and programmatically.

[Copilot]

Copilot review overview

🟢 Approval recommended

No unresolved issues were identified.

Review effort: Lite
Findings: None

What changed in this PR

Adds artifact downloads and asset uploads to the Python client, improves CLI result-output handling, and updates documentation.

Changes:

• Added secure transfer APIs and tests.
• Added explicit CLI output modes and stdout support.
• Added API workflow documentation and navigation.

File	Summary
tests/​test_transfers.py	Transfer contract and failure tests
tests/​test_cli.py	CLI output-mode coverage
src/​subfork/​resources.py	Artifact and asset APIs
src/​subfork/​client.py	Transfer handling and resource registration
src/​subfork/​cli.py	Explicit result-output behavior
README.md	Updated usage references
docs/​usage.md	API guide reference
docs/​mkpages.yml	API navigation entry
docs/​cli.md	Updated CLI documentation
docs/​api.md	New API workflow guide

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.