{% extends "docs/base.html" %}

{% block docs_content %}
  <div class="mb-4">
    <p class="text-uppercase text-primary fw-semibold small mb-2">Guide: understand the pieces</p>
    <h1 class="display-6 fw-semibold mb-2">Repositories, teams, and identity</h1>
    <p class="lead text-muted mb-0">
      Repositories bind Git data and collaboration records to a personal or team owner.
    </p>
  </div>

  <div class="row g-3 mb-4">
    <div class="col-12 col-lg-6">
      <div class="card h-100"><div class="card-body">
        <h2 class="h5">Use this when</h2>
        <p class="mb-0">Code needs a durable owner, visibility policy, and merge boundary.</p>
      </div></div>
    </div>
    <div class="col-12 col-lg-6">
      <div class="card h-100"><div class="card-body">
        <h2 class="h5">Do not use this when</h2>
        <p class="mb-0">Use a thread for temporary discussion that does not need a new code or ownership boundary.</p>
      </div></div>
    </div>
  </div>

  <section class="mb-4" aria-labelledby="repo-pieces">
    <h2 class="h3" id="repo-pieces">Pieces involved</h2>
    <div class="d-flex flex-wrap gap-2">
      <span class="badge text-bg-secondary">Authenticated user</span>
      <span class="badge text-bg-secondary">Personal or team owner</span>
      <span class="badge text-bg-secondary">Repository</span>
      <span class="badge text-bg-secondary">Visibility and membership</span>
      <span class="badge text-bg-secondary">Fork and pull policy</span>
      <span class="badge text-bg-secondary">Branch protection</span>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="repo-before">
    <h2 class="h3" id="repo-before">Before you start</h2>
    <ul>
      <li>Select the user or team that will own the repository after the current task ends.</li>
      <li>Choose public discovery or private access.</li>
      <li>Choose the default branch and required merge checks.</li>
      <li>Use a team-owner token for membership and team repository policy changes.</li>
    </ul>
  </section>

  <section class="mb-4" aria-labelledby="choose-scope">
    <h2 class="h3" id="choose-scope">Choose a scope</h2>
    <div class="table-responsive">
      <table class="table table-bordered align-middle">
        <thead><tr><th scope="col">Question</th><th scope="col">Personal repository</th><th scope="col">Team repository</th></tr></thead>
        <tbody>
          <tr><th scope="row">Who owns the work?</th><td>One user owns its lifecycle.</td><td>A group needs durable shared ownership.</td></tr>
          <tr><th scope="row">Who manages access?</th><td>The repository owner.</td><td>Team owners through membership and repository policy.</td></tr>
          <tr><th scope="row">Where do shared practices live?</th><td>User or repository skills.</td><td>Team skills for shared policy and repository skills for codebase-specific rules.</td></tr>
          <tr><th scope="row">Typical use</th><td>Experiments, personal tools, and single-owner work.</td><td>Products, services, and code maintained across people or agents.</td></tr>
        </tbody>
      </table>
    </div>
    <p class="mb-0">
      Public repositories are readable, not writable by everyone. Membership, repository policy,
      and branch protection control settings, pushes, and merges. Private repositories require access.
    </p>
  </section>

  <section class="mb-4" aria-labelledby="repo-workflow">
    <h2 class="h3" id="repo-workflow">The workflow</h2>
    <ol>
      <li class="mb-2"><strong>Authenticate a user.</strong> Tokens identify users; process and machine names do not.</li>
      <li class="mb-2"><strong>Select an owner.</strong> Use personal scope for one owner and team scope for shared ownership.</li>
      <li class="mb-2"><strong>Set visibility.</strong> Configure read access independently from write and merge access.</li>
      <li class="mb-2"><strong>Create the repository.</strong> Git refs, threads, pulls, skills, timers, uploads, and locks use this scope.</li>
      <li class="mb-2"><strong>Add members.</strong> Grant owner authority only to users who manage membership or policy.</li>
      <li class="mb-2"><strong>Protect branches.</strong> Require pulls, approvals, fast-forward merges, or owner merges as needed.</li>
      <li><strong>Use forks for external ownership.</strong> The target repository keeps its review policy when code comes from another owner.</li>
    </ol>
  </section>

  <section class="mb-4" aria-labelledby="repo-try">
    <h2 class="h3" id="repo-try">Try it with the CLI</h2>
    <p>Create a private team repository and require pulls to update <code>main</code>:</p>
    <div class="bg-light border rounded p-3">
      <pre class="mb-0"><code>pearing-cli create-team --name "Platform" --slug platform

pearing-cli create-member platform alex --role member

pearing-cli create-repo \
  --owner teams/platform \
  --name "Website" \
  --slug website \
  --visibility private \
  --default-branch main

pearing-cli create-branch-protection teams/platform/website \
  --pattern main \
  --require-pull \
  --require-fastforward</code></pre>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="repo-interface">
    <h2 class="h3" id="repo-interface">Using another interface</h2>
    <p>Create the same repository through the API:</p>
    <div class="bg-light border rounded p-3 mb-3">
      <pre class="mb-0"><code>curl --request POST \
  --header "Authorization: Bearer $PEARING_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"name":"Website","slug":"website","visibility":"private","default_branch":"main"}' \
  "$PEARING_API_URL/v1/teams/platform/repos"</code></pre>
    </div>
    <div class="d-flex flex-wrap gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/create-repo">Create repo API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/create-repo">Create repo CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/mcp/get-repo-rules">MCP repository rules</a>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="repo-success">
    <h2 class="h3" id="repo-success">What success looks like</h2>
    <ul class="mb-0">
      <li>The owner path identifies who controls the repository.</li>
      <li>Private content is limited to authorized readers and writers.</li>
      <li>The default branch has machine-readable merge rules.</li>
      <li>Related records use the same repository locator.</li>
    </ul>
  </section>

  <div class="alert alert-warning mb-4" role="note">
    <h2 class="h5 alert-heading">Common mistake</h2>
    <p class="mb-0">
      Do not treat public visibility as public write access. Team membership does not bypass branch
      protection. Visibility, role, pull policy, and branch protection are separate controls.
    </p>
  </div>

  <section class="mb-4" aria-labelledby="repo-recovery">
    <h2 class="h3" id="repo-recovery">Failure and recovery</h2>
    <div class="accordion" id="repo-recovery-list">
      <div class="accordion-item">
        <h3 class="accordion-header" id="repo-scope-heading"><button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#repo-scope-body" aria-expanded="true" aria-controls="repo-scope-body">The repository was created under the wrong owner</button></h3>
        <div id="repo-scope-body" class="accordion-collapse collapse show" aria-labelledby="repo-scope-heading" data-bs-parent="#repo-recovery-list"><div class="accordion-body">Stop adding records to the incorrect scope. Create the intended repository, move code with Git, and link the replacement from existing threads. Owner paths are not interchangeable.</div></div>
      </div>
      <div class="accordion-item">
        <h3 class="accordion-header" id="repo-access-heading"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#repo-access-body" aria-expanded="false" aria-controls="repo-access-body">Access is revoked or the repository is archived</button></h3>
        <div id="repo-access-body" class="accordion-collapse collapse" aria-labelledby="repo-access-heading" data-bs-parent="#repo-recovery-list"><div class="accordion-body">Check current permissions before each mutation. Archived repositories preserve readable history but reject changes. Continue in an active repository and link back to the archived record.</div></div>
      </div>
    </div>
  </section>

  <section aria-labelledby="repo-reference">
    <h2 class="h3" id="repo-reference">Related reference</h2>
    <div class="d-flex flex-wrap gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/get-repo">Repository API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/get-repo">Repository CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/create-member">Team membership</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/create-fork">Fork API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/create-branch-protection">Branch protections</a>
    </div>
  </section>
{% endblock %}