<?php
/*
 * Owner-only guide: Files & Deliverables.
 * Served by modules/Help/HelpController (topic = "owner_deliverables").
 * Gated to the platform owner alone (OWNER_TOPICS).
 */
?>

<h1><i class="bi bi-send-fill"></i> Owner: Files &amp; Deliverables</h1>
<p class="lead">A complete map of where everything lives — so you never have to guess
which files matter, and cleaning the build folder never deletes anything important.
It also explains how to update &amp; download the two things you ship by hand:
the <strong>Marketing Website</strong> and the <strong>Community Installer</strong>.</p>

<div class="alert alert-info">
    <strong>Who is this for?</strong> The platform owner. The menu lives under your
    account dropdown → <strong>Deliverables</strong>, and both this guide and those
    pages are hidden from everyone else.
</div>

<div class="card border-0 shadow-sm my-3" style="background:var(--pp-surface-soft,#f8fafc)">
  <div class="card-body">
    <h5 class="mb-3"><i class="bi bi-lightning-charge-fill text-warning"></i> Updating them in future — the short version</h5>
    <div class="row g-3">
      <div class="col-md-6">
        <h6 class="text-uppercase small text-muted mb-2"><i class="bi bi-globe2"></i> Marketing site</h6>
        <ol class="mb-0 ps-3" style="font-size:.92rem">
          <li>Edit files in <code>Extra/MarketingSite/</code>.</li>
          <li><strong>Deliverables → Marketing Website → Download ZIP</strong> (always current — no build).</li>
          <li>Upload to your domain root.</li>
        </ol>
      </div>
      <div class="col-md-6">
        <h6 class="text-uppercase small text-muted mb-2"><i class="bi bi-box-seam"></i> Community forum</h6>
        <ol class="mb-0 ps-3" style="font-size:.92rem">
          <li>Edit code in <code>Extra/CommunityPortal/custom/</code> (or the console).</li>
          <li><strong>Deliverables → Community Installer → Rebuild</strong> (it flags changes).</li>
          <li><strong>Download ZIP</strong> — unzip on a server, open <code>install.php</code>.</li>
        </ol>
      </div>
    </div>
    <p class="mb-0 mt-3" style="font-size:.86rem"><i class="bi bi-shield-check text-success"></i>
      Your source lives in <code>Extra/</code> — <strong>back that up</strong>. The
      <code>output/</code> folder is disposable; cleaning it is safe, and Download rebuilds it for you.</p>
  </div>
</div>

<h2>Contents</h2>
<ul>
    <li><a href="#rule">The one rule: source vs. build</a></li>
    <li><a href="#map">The file map</a></li>
    <li><a href="#marketing">Marketing Website — edit &amp; download</a></li>
    <li><a href="#community">Community Installer — edit, rebuild &amp; download</a></li>
    <li><a href="#staleness">Staleness &amp; the rebuild-before-download safety</a></li>
    <li><a href="#installer">What the installer does on the far end</a></li>
    <li><a href="#cleaning">Cleaning the output folder safely</a></li>
</ul>

<h2 id="rule">The one rule: source vs. build</h2>
<p>Everything in the platform is one of two kinds of thing:</p>
<div class="table-responsive">
<table class="table table-bordered align-middle">
    <thead><tr><th>Kind</th><th>Where</th><th>Safe to delete?</th></tr></thead>
    <tbody>
        <tr>
            <td><strong>Source</strong> — you (or the platform) author it</td>
            <td><code>Extra/</code> and <code>projects/</code> in the app root</td>
            <td>❌ No — back it up</td>
        </tr>
        <tr>
            <td><strong>Build output</strong> — the machine generates it</td>
            <td><code>../ppphp/output/</code> (outside this app)</td>
            <td>✅ Yes — it regenerates on the next build</td>
        </tr>
    </tbody>
</table>
</div>
<p>Your two deliverables are kept in the safe, human-named <code>Extra/</code> folder
(and the platform's <code>projects/</code> system), <strong>never</strong> in
<code>output/</code>. So cleaning <code>output/</code> can never lose your work.</p>

<h2 id="map">The file map</h2>
<div class="table-responsive">
<table class="table table-bordered align-middle">
    <thead><tr><th>Path</th><th>What it is</th></tr></thead>
    <tbody>
        <tr><td><code>Extra/</code></td><td>Safe home for hand-maintained deliverables. Has its own <code>README.md</code>.</td></tr>
        <tr><td><code>Extra/MarketingSite/</code></td><td>The public <strong>ppradhan.com</strong> site (static HTML/CSS/JS + <code>docs/</code>). Edit these files directly.</td></tr>
        <tr><td><code>Extra/CommunityPortal/custom/</code></td><td><strong>The forum's own code</strong> — what you edit for features: <code>public-routes.php</code> (router) and <code>forum/*.php</code> (<code>home.php</code>, <code>question.php</code>, <code>profile.php</code>, <code>action.php</code>, <code>search.php</code>, and <code>_shell.php</code> = shared helpers + all CSS). Edit here or in the console's Custom Files editor — same files.</td></tr>
        <tr><td><code>projects/admin/community/custom</code></td><td>A <strong>symlink</strong> → <code>Extra/CommunityPortal/custom/</code>. So the build + console read the forum code from Extra. Only one copy exists.</td></tr>
        <tr><td><code>projects/admin/community/config/</code></td><td>Community project design (edited in the console, not as loose files): <code>pages.json</code>, <code>tables.json</code>, <code>designer.json</code>, <code>output.json</code> (build target + installer toggle), <code>security.json</code>, <code>misc.json</code> (timezone/advanced).</td></tr>
        <tr><td><code>../ppphp/output/community/</code></td><td>The <strong>built</strong> community app the installer ZIP is made from: <code>install.php</code>, <code>database.sql</code>, <code>config/database.sample.php</code>, <code>generated/</code>, <code>core/</code>, <code>assets/</code>. Regenerable.</td></tr>
    </tbody>
</table>
</div>

<h2 id="marketing">Marketing Website — edit &amp; download</h2>
<p>The marketing site is <strong>static</strong> — there is nothing to build.</p>
<ol>
    <li>Edit the files in <code>Extra/MarketingSite/</code> (e.g. <code>index.html</code>, <code>assets/</code>, <code>docs/</code>).</li>
    <li>Open <strong>Deliverables → Marketing Website</strong>.</li>
    <li>Click <strong>Download ZIP</strong> — it zips the current folder live, so your edit is always included. No rebuild step.</li>
    <li>Unzip into your domain's web root. It sits <em>alongside</em> <code>/community</code>, not inside it.</li>
</ol>
<div class="alert alert-secondary">The ZIP is built on demand, streamed to your browser, then deleted from the server — nothing is left behind.</div>

<h2 id="community">Community Installer — edit, rebuild &amp; download</h2>
<p>The community forum is a generated app, so its ZIP is a package of the
<strong>built output</strong>. That means a change you make to the source only
reaches the ZIP after a <strong>Rebuild</strong>.</p>
<ol>
    <li>Change the forum: edit <code>Extra/CommunityPortal/custom/</code> (or use the console's <strong>Custom Files</strong> editor — same files), and/or tweak the design in the Designer.</li>
    <li>Open <strong>Deliverables → Community Installer</strong>. If it sees your edits it shows <em>“Changes since last build — Rebuild recommended.”</em></li>
    <li>Click <strong>Rebuild</strong> (regenerates <code>output/community/</code>).</li>
    <li>Click <strong>Download ZIP</strong>. (It also rebuilds automatically if anything is unbuilt — see below.)</li>
    <li>Unzip on any server and open <code>install.php</code>.</li>
</ol>
<div class="alert alert-warning">
    The installer bundle is only produced when the project's <strong>Output → Advanced →
    “Include standalone install.php”</strong> toggle is on. It is, for this project.
    Turn it off and the download won't carry <code>install.php</code>.
</div>

<h2 id="staleness">Staleness &amp; the rebuild-before-download safety</h2>
<p>Two things keep you from ever shipping a stale or missing bundle:</p>
<ul>
    <li><strong>Staleness badge.</strong> The page compares the community project's source
        (config + custom files) against the last build time. If the source is newer, it
        flags <em>“Rebuild recommended.”</em></li>
    <li><strong>Rebuild-before-download.</strong> When you click <strong>Download</strong>,
        the server first checks whether the output is missing (e.g. you cleaned
        <code>output/</code>) or out of date — and if so, <strong>rebuilds automatically</strong>
        before zipping. So the download is always fresh, and a wiped output folder
        self-heals.</li>
</ul>
<div class="alert alert-info">
    <strong>Content vs. code.</strong> Forum content (categories, questions, answers) lives
    in the <em>database</em>, not in files — a timestamp check can't see those changes.
    The build snapshots the current database into <code>database.sql</code> at build time,
    so after editing content, rebuild to refresh what the installer seeds.
</div>

<h2 id="installer">What the installer does on the far end</h2>
<p>When someone unzips your bundle and opens <code>install.php</code>, it:</p>
<ol>
    <li>asks for the database host / name / user / password (with a <strong>Test connection</strong> button);</li>
    <li>writes <code>config/database.php</code> and imports <code>database.sql</code> (schema + starter content);</li>
    <li>creates the first administrator from credentials they choose;</li>
    <li>self-locks (<code>config/installed.lock</code>) so it can't be re-run to wipe data, and offers to delete itself.</li>
</ol>
<p><strong>No credentials ever ship in the ZIP</strong> — the download excludes
<code>config/database.php</code> and the lock file, and installer-mode builds don't bake a
dev admin. The bundle carries only <code>config/database.sample.php</code>.</p>

<h2 id="cleaning">Cleaning the output folder safely</h2>
<p>You can safely delete anything under <code>../ppphp/output/</code> whenever it gets
cluttered. Nothing there is irreplaceable:</p>
<ul>
    <li>The community output rebuilds from its project — automatically on the next Download, or when you click Rebuild.</li>
    <li>The marketing site isn't in <code>output/</code> at all; it's in <code>Extra/MarketingSite/</code>.</li>
</ul>
<p><strong>Back up instead:</strong> <code>Extra/</code> and <code>projects/</code>. Those are your source of truth.</p>

<div class="alert alert-secondary mt-4">
    <i class="bi bi-folder2-open"></i> On-disk copies of this map live in
    <code>Extra/README.md</code> and <code>Extra/CommunityPortal/README.md</code>.
</div>
