docs(oss): complete adopter journey

CODE_OF_CONDUCT.md

@@ -0,0 +1,151 @@
+# Contributor Covenant 3.0 Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the
+dignity, rights, and contributions of all individuals, regardless of
+characteristics including race, ethnicity, caste, color, age, physical
+characteristics, neurodiversity, disability, sex or gender, gender identity or
+expression, sexual orientation, language, philosophy or religion, national or
+social origin, socio-economic position, level of education, or other status.
+The same privileges of participation are extended to everyone who participates
+in good faith and in accordance with this Covenant.
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our
+community's expectations for positive behavior. We also understand that our
+words and actions may be interpreted differently than we intend based on
+culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each
+other and act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of
+   gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our
+   community**.
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances,
+threats, and promotion of these behaviors are violations of this Code of
+Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in
+   unnecessary personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments
+   directed at a community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone's personality or
+   behavior on the basis of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered
+   inappropriately intimate in the context or purpose of the community.
+5. **Violating confidentiality.** Sharing or acting on someone's personal or
+   private information without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other
+   harm toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or
+   pretending to be someone else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content
+   you contribute.
+3. **Promotional materials.** Sharing marketing or other commercial content in
+   a way that is outside the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content
+   which includes, links, or describes any other restricted behaviors.
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their
+best to collaborate. Not every conflict represents a code of conduct
+violation, and this Code of Conduct reinforces encouraged behaviors and norms
+that can help avoid conflicts and minimize harm.
+
+Use the repository host's private reporting form on the Security tab to report
+a possible violation. Start the report title with `Code of Conduct:`. Do not
+open a public issue. The repository owner serves as the Community Moderator
+and receives these private reports. If a report concerns the repository owner,
+use GitHub's content-reporting or support channel instead.
+
+The Community Moderator takes reports of violations seriously and will make
+every effort to respond in a timely manner. The moderator will investigate
+reports by reviewing relevant messages, logs, recordings, or witness accounts.
+The moderator will keep investigation and enforcement actions as transparent
+as possible while prioritizing safety and confidentiality. Enforcement actions
+are carried out in private with the involved parties, but communicating to the
+whole community may be part of a mutually agreed resolution.
+
+## Addressing and Repairing Harm
+
+If an investigation finds that this Code of Conduct has been violated, the
+following enforcement ladder may be used to determine how best to repair harm.
+The decision depends on the incident's impact on the people involved and the
+community as a whole. Depending on the severity of a violation, lower rungs on
+the ladder may be skipped.
+
+1. **Warning**
+   1. Event: A violation involving a single incident or series of incidents.
+   2. Consequence: A private, written warning from the Community Moderator.
+   3. Repair: Examples include a private written apology, acknowledgement of
+      responsibility, and seeking clarification on expectations.
+2. **Temporarily Limited Activities**
+   1. Event: A repeated violation that previously resulted in a warning, or the
+      first occurrence of a more serious violation.
+   2. Consequence: A private, written warning with a time-limited cooldown
+      period. The period may limit particular communication channels or
+      interactions with particular community members.
+   3. Repair: Examples include making an apology, reflecting on actions and
+      impact, and being thoughtful about re-entering community spaces.
+3. **Temporary Suspension**
+   1. Event: A pattern of repeated violations that warnings did not resolve, or
+      a single serious violation.
+   2. Consequence: A private written warning with conditions for return from
+      suspension.
+   3. Repair: Examples include respecting the spirit of the suspension, meeting
+      the conditions for return, and reintegrating thoughtfully.
+4. **Permanent Ban**
+   1. Event: A pattern that other steps did not resolve, or a violation so
+      serious that the moderator cannot keep the community safe with this
+      person as a member.
+   2. Consequence: Access to all community spaces, tools, and communication
+      channels is removed. Permanent bans should be rare and supported by
+      strong reasoning.
+   3. Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is a guideline. It does not limit the Community
+Moderator's discretion and judgment when acting in the community's best
+interests.
+
+## Scope
+
+This Code of Conduct applies within all community spaces. It also applies when
+an individual officially represents the community in public or other spaces.
+Examples include using an official email address, posting through an official
+social account, or acting as an appointed representative at an online or
+offline event.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0,
+permanently available at
+[https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and
+licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
+The enforcement ladder was inspired by the work of
+[Mozilla's code of conduct team](https://github.com/mozilla/inclusion).
+
+For more guidance, see the Contributor Covenant
+[FAQ](https://www.contributor-covenant.org/faq),
+[translations](https://www.contributor-covenant.org/translations), and
+[resources](https://www.contributor-covenant.org/resources).

README.md

@@ -51,6 +51,33 @@ go install github.com/nstranquist/wip-commit/cmd/wip@v0.1.0-beta.1
 
 Before you run that command, verify that the tag exists at that public address.
 
+## Quick start
+
+Build the current checkout, then start the setup wizard inside the Git
+repository where you want to capture work:
+
+```text
+go build -trimpath -o ./bin/wip ./cmd/wip
+./bin/wip init
+```
+
+The wizard prints the lane environment command. Load it in the agent shell,
+stage only owned paths, review the proposed groups, and capture them:
+
+```text
+eval "$(./bin/wip env --lane <lane-id>)"
+git add -- <owned-path>...
+./bin/wip plan
+./bin/wip commit
+./bin/wip release
+```
+
+Use a linked worktree when one agent should own the complete checkout. Use
+shared mode when cooperating agents need disjoint path leases in one checkout.
+Automation should pass an exact JSON plan. Start with
+[examples/shared-split-plan.json](examples/shared-split-plan.json) and replace
+every message, path, and verification command with reviewed project values.
+
 ## Use the agent skill
 
 The portable skill is in [skills/wip-commit](skills/wip-commit). Install that
@@ -136,7 +163,27 @@ The command uses `git worktree add --detach`. It refuses to replace an existing
 directory. If an existing directory contains a matching linked worktree at the
 requested base, the command reuses it.
 
-## Capture work
+## Configuration
+
+`wip` has no repository configuration file and no background service. The
+`wip init` command records the selected lane, worktree, owner, and path leases
+below the repository's common Git directory. Linked worktrees therefore share
+one coordination domain.
+
+Use `--repo-dir` to select a repository without changing directories. Use
+`--json` when a program needs typed results. `wip env` exports `WIP_LANE`,
+`WIP_AGENT`, and `WIP_SESSION` for later commands. An explicit
+`GIT_INDEX_FILE` selects the caller's source index; other inherited
+repository-routing variables do not override the selected repository.
+
+Commit plans hold per-group verification commands and optional timeouts. The
+default verification and hook timeout is two minutes, and the maximum is 24
+hours. Keep secrets and machine-specific paths out of plan files and commit
+messages.
+
+## Usage
+
+### Capture work
 
 Load the lane identity in each agent shell:
 
@@ -317,6 +364,32 @@ Reconciliation compares the target ref, every parent, tree, message, changed pat
 allowed scope, and final tree before it updates lane metadata. Exact retries are
 idempotent.
 
+## Troubleshooting
+
+Start with structured state evidence:
+
+```text
+wip --json doctor
+wip --json status
+```
+
+Do not stash, reset, clean, delete state, or force-update a lane ref during
+recovery. Common actions are:
+
+- `LANE_NOT_ACTIVE`: run `wip init`, or load the exact lane identity.
+- `PATH_LEASE_CONFLICT`: select disjoint paths or wait for the owner to release
+  its lease.
+- `SOURCE_INDEX_MOVED`: inspect the selected staged paths and rerun the complete
+  plan.
+- `LOCK_TIMEOUT`: inspect active lanes, wait for the current operation, and
+  retry.
+- `ref_updated: true`: preserve `plan_id` and `plan_digest`, then run the exact
+  `wip reconcile` command.
+
+[The error and recovery guide](docs/ERRORS.md) lists every typed code and its
+required action. [SUPPORT.md](SUPPORT.md) explains what evidence is safe to
+include in a report.
+
 ## Safety scope
 
 `wip` protects coordination between cooperating local processes. It does not
@@ -355,6 +428,7 @@ changes. These procedures do not authorize a push or release tag.
 Project authority and succession are in [GOVERNANCE.md](GOVERNANCE.md).
 Current support and safe incident-reporting guidance are in
 [SUPPORT.md](SUPPORT.md). Security reports use [SECURITY.md](SECURITY.md).
+Community participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
 The [open source practice guide](docs/OSS-PRACTICE-GUIDE.md) maps official
 guidance to project rules and records when maintainers must review it again.
 Local self-hosting receipts and safe-failure results are in

SUPPORT.md

@@ -19,9 +19,10 @@ credentials in a report.
 For a security issue, follow [SECURITY.md](SECURITY.md). Do not report a
 suspected vulnerability in a public issue.
 
-A confidential conduct-reporting channel is not configured in this local
-checkout. The public-beta plan requires the owner to configure that channel and
-approve a Code of Conduct before the project solicits public contributions.
+Community participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Use
+the repository host's private reporting form on the Security tab for a
+confidential conduct report. Start the title with `Code of Conduct:`. Do not
+put a conduct report in a public issue.
 
 ## Report a capture problem
 

docs/OSS-PUBLIC-BETA.requirements.yaml

@@ -326,7 +326,8 @@
       "human_gate": true,
       "acceptance": "Before public contributions are solicited, the owner approves a Code of Conduct, names its enforcement responsibility, and configures a confidential conduct-reporting path.",
       "evidence": [
-        {"kind": "gap", "value": "No approved Code of Conduct or confidential conduct-reporting channel exists in this local checkout.", "observed_on": "2026-08-16"}
+        {"kind": "configuration", "value": "GitHub private vulnerability reporting is enabled and supplies the confidential repository channel named in SUPPORT.md and the proposed Code of Conduct.", "observed_on": "2026-08-17"},
+        {"kind": "human-gate", "value": "CODE_OF_CONDUCT.md names the repository owner as moderator and adapts Contributor Covenant 3.0. Owner review and merge remain required before contributions are solicited.", "observed_on": "2026-08-17"}
       ]
     },
     {

examples/README.md

@@ -0,0 +1,18 @@
+# Commit plan examples
+
+The files in this directory show the JSON shape for a commit plan. Pass an
+edited file with `wip commit --plan <file>`. These files are templates, not
+commands to run unchanged.
+
+Before you use an example:
+
+1. Replace every path with a staged path in the active lane's lease.
+2. Replace every message with a concrete Conventional Commit subject.
+3. Replace each verification command with a bounded command for the candidate
+   tree.
+4. Run `wip plan` and compare its path groups with the edited file.
+5. Run `wip commit --plan <file>`.
+
+The command rejects paths outside the lease, duplicate files, vague messages,
+and verification commands that fail or time out. It leaves the source `HEAD`
+and complete index unchanged.

examples/shared-split-plan.json

@@ -0,0 +1,24 @@
+[
+  {
+    "message": "fix(parser): preserve source error locations",
+    "files": [
+      "internal/parser"
+    ],
+    "verify": [
+      {
+        "argv": [
+          "go",
+          "test",
+          "./internal/parser"
+        ],
+        "timeout_ms": 120000
+      }
+    ]
+  },
+  {
+    "message": "docs(parser): explain source error locations",
+    "files": [
+      "docs/parser.md"
+    ]
+  }
+]