Skip to content

Document common sandbox startup failures #1

Description

@lpc0387

1. Document common sandbox startup failures

Labels: good first issue, documentation, sandbox

Body:

New users may hit predictable sandbox setup problems: a busy port, missing editable install, a stale demo database, or confusion about mock mode versus --real. Add a short troubleshooting section to sandbox/README.md that explains these cases and points back to the existing safe defaults.

Suggested scope:

  • Keep the section concise and beginner-friendly.
  • Mention ./scripts/start_sandbox.sh --port 8877 for port conflicts.
  • Mention that mock mode is the default and does not call real workers.
  • Mention that generated databases and logs should not be committed.
  • Do not add new runtime behavior.

Acceptance criteria:

  • sandbox/README.md has a new troubleshooting section covering at least three common startup problems.
  • The section preserves the repository safety boundary around mock data, runtime databases, and secrets.
  • Existing quick-start commands remain unchanged unless they are being clarified.
  • Verification notes include a Markdown review and, if shell snippets are changed, bash -n scripts/start_sandbox.sh.

Why it is newcomer-friendly:

This is a documentation-only task with a clear target file, concrete examples, and no need to understand the full collaboration engine internals.


This issue was created from the v5.0 launch backlog in docs/launch/good-first-issues.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is neededsandboxSandbox demo and isolated execution

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions