<?php
declare(strict_types=1);
require_once __DIR__ . '/includes/bootstrap.php';

$uiLang   = dbnToolsCurrentLanguage();
$isAuthed = dbnToolsIsAuthenticated();
$langPath = '/advocate-guide.php';
$toolsLogin  = 'https://dobetternorge.no/tools-login.php?return=' . urlencode('/advocate.php');
$registerUrl = 'https://dobetternorge.no/register.php';
$ctaUrl = $isAuthed ? '/advocate.php' : $toolsLogin;

$_pt = require __DIR__ . '/translations/advocate-guide.php';
$t   = $_pt[$uiLang] ?? $_pt['en'];
?>
<!doctype html>
<html lang="<?= htmlspecialchars($uiLang) ?>">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Advocate User Guide — How to generate partisan legal briefs · Do Better Norge Tools</title>
    <meta name="description" content="Step-by-step guide to using Advocate: selecting your party role, configuring corpus slices, uploading case files, and reading the adversarial brief output.">
    <meta name="robots" content="index, follow">
    <link rel="canonical" href="https://tools.dobetternorge.no/advocate-guide.php">
    <meta property="og:title" content="Advocate User Guide — How to generate partisan legal briefs">
    <meta property="og:description" content="Learn every Advocate control: role selection, corpus slices, advanced settings, file upload, output panels, and the counter-brief feature.">
    <meta property="og:type" content="website">
    <meta name="theme-color" content="#00205B">
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Crimson+Pro:wght@400;600;700&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap">
    <link rel="stylesheet" href="assets/css/tools.css">
    <link rel="stylesheet" href="assets/css/dbn-tools-redesign.css">
</head>
<body class="kdoc-page">

<header class="lt-nav">
    <a href="https://dobetternorge.no" class="lt-nav__brand">
        <picture>
            <source srcset="assets/images/logo-header.webp" type="image/webp">
            <img class="lt-nav__logo" src="assets/images/logo-header.png" alt="Do Better Norge" width="140" height="36" loading="eager">
        </picture>
        <span class="lt-nav__badge">Legal Tools</span>
    </a>
    <div class="lt-nav__right">
        <nav class="shell-lang-switcher" aria-label="Language">
<?php foreach (dbnToolsSupportedLanguages() as $langCode): ?>
            <a href="<?= htmlspecialchars($langPath . '?lang=' . $langCode) ?>" class="<?= $langCode === $uiLang ? 'is-active' : '' ?>"><?= htmlspecialchars(dbnToolsLanguageLabel($langCode)) ?></a>
<?php endforeach; ?>
        </nav>
<?php if ($isAuthed): ?>
        <a href="/advocate.php" class="lt-nav__cta lt-nav__cta--enter"><?= htmlspecialchars($t['nav_open']) ?></a>
<?php else: ?>
        <a href="<?= htmlspecialchars($toolsLogin) ?>" class="lt-nav__cta"><?= htmlspecialchars($t['nav_signin']) ?></a>
<?php endif; ?>
    </div>
</header>

<nav class="kdoc-doc-nav" aria-label="Advocate documentation">
    <div class="kdoc-doc-nav__inner">
        <a href="/advocate-about.php"><?= htmlspecialchars($t['nav_about']) ?></a>
        <a href="/advocate-guide.php" class="is-active"><?= htmlspecialchars($t['nav_guide']) ?></a>
        <a href="/advocate-tech.php"><?= htmlspecialchars($t['nav_howit']) ?></a>
        <?php if ($isAuthed): ?>
        <a href="/advocate.php"><?= htmlspecialchars($t['nav_opentool']) ?></a>
        <?php endif; ?>
    </div>
</nav>

<!-- Hero -->
<section class="kdoc-hero" style="background: linear-gradient(rgba(0,20,60,0.78),rgba(0,20,60,0.86)), url('assets/images/advocate/hero-guide.png') center/cover no-repeat;">
    <div class="kdoc-hero__inner">
        <p class="kdoc-hero__kicker"><?= htmlspecialchars($t['hero_kicker']) ?></p>
        <h1 class="kdoc-hero__title"><?= htmlspecialchars($t['hero_title']) ?></h1>
        <p class="kdoc-hero__sub"><?= htmlspecialchars($t['hero_sub']) ?></p>
    </div>
</section>

<!-- Table of contents -->
<div class="kdoc-section">
    <p class="kdoc-section__eyebrow"><?= htmlspecialchars($t['toc_title']) ?></p>
    <nav class="kdoc-toc" aria-label="Guide contents">
        <a href="#s1"><?= htmlspecialchars($t['s1_head']) ?></a>
        <a href="#s2"><?= htmlspecialchars($t['s2_head']) ?></a>
        <a href="#s3"><?= htmlspecialchars($t['s3_head']) ?></a>
        <a href="#s4"><?= htmlspecialchars($t['s4_head']) ?></a>
        <a href="#s5"><?= htmlspecialchars($t['s5_head']) ?></a>
        <a href="#s6"><?= htmlspecialchars($t['s6_head']) ?></a>
        <a href="#s7"><?= htmlspecialchars($t['s7_head']) ?></a>
        <a href="#s8"><?= htmlspecialchars($t['s8_head']) ?></a>
        <a href="#s9"><?= htmlspecialchars($t['s9_head']) ?></a>
        <a href="#s10"><?= htmlspecialchars($t['s10_head']) ?></a>
        <a href="#s11"><?= htmlspecialchars($t['s11_head']) ?></a>
    </nav>
</div>

<!-- Step 1: Language -->
<section class="kdoc-section--alt" id="s1">
<div class="kdoc-section">
    <h2 class="kdoc-guide-step__title"><?= htmlspecialchars($t['s1_title']) ?></h2>
    <p class="kdoc-guide-step__body"><?= htmlspecialchars($t['s1_body']) ?></p>
    <img src="assets/images/advocate/form-top.png" alt="Advocate form top showing language pills, role selector, and engine options" class="kdoc-screenshot" loading="lazy">
</div>
</section>

<!-- Step 2: Role -->
<div class="kdoc-section" id="s2">
    <h2 class="kdoc-guide-step__title"><?= htmlspecialchars($t['s2_title']) ?></h2>
    <p class="kdoc-guide-step__body"><?= htmlspecialchars($t['s2_body']) ?></p>
    <div class="kdoc-table-wrap">
        <table class="kdoc-table">
            <thead>
                <tr>
                    <th><?= htmlspecialchars($t['s2_table_col1']) ?></th>
                    <th><?= htmlspecialchars($t['s2_table_col2']) ?></th>
                    <th><?= htmlspecialchars($t['s2_table_col3']) ?></th>
                </tr>
            </thead>
            <tbody>
                <tr><td>Biological mother</td><td>barneloven · ECHR Art. 8</td><td>Opposing or challenging care orders, contact restrictions</td></tr>
                <tr><td>Biological father</td><td>barneloven · ECHR Art. 8</td><td>Contact rights, parental involvement, procedural challenges</td></tr>
                <tr><td>Both biological parents</td><td>barneloven · barnevernsloven</td><td>Joint challenge to omsorgsovertakelse or placement decisions</td></tr>
                <tr><td>Foster carer / long-term placement</td><td>barnevernsloven § 4-19a</td><td>Opposing reunification or arguing for continued placement</td></tr>
                <tr><td>Adoptive parent</td><td>adopsjonsloven · barnevernsloven</td><td>Adoption approval challenges, post-adoption contact disputes</td></tr>
                <tr><td>Child (via representative)</td><td>barneloven · FNs barnekonvensjon</td><td>Child's independent interests — <em>barnets beste</em> arguments</td></tr>
                <tr><td>Extended family</td><td>barneloven · ECHR Art. 8</td><td>Grandparent/sibling contact or kinship placement claims</td></tr>
                <tr><td>Child welfare services (Barnevernet)</td><td>barnevernsloven · fvl</td><td>Defending care orders, justifying interventions</td></tr>
                <tr><td>Other</td><td>fvl (general)</td><td>Describe in the custom text field — agent adapts framing</td></tr>
            </tbody>
        </table>
    </div>
    <img src="assets/images/advocate/role-selector.png" alt="Role selector dropdown open showing all 9 party options" class="kdoc-screenshot" loading="lazy">
</div>

<!-- Step 3: Case description -->
<section class="kdoc-section--alt" id="s3">
<div class="kdoc-section">
    <h2 class="kdoc-guide-step__title"><?= htmlspecialchars($t['s3_title']) ?></h2>
    <p class="kdoc-guide-step__body"><?= htmlspecialchars($t['s3_body']) ?></p>
    <p class="kdoc-guide-step__tip"><strong>&#128161;</strong> <?= htmlspecialchars($t['s3_tip']) ?></p>
</div>
</section>

<!-- Step 4: Engine -->
<div class="kdoc-section" id="s4">
    <h2 class="kdoc-guide-step__title"><?= htmlspecialchars($t['s4_title']) ?></h2>
    <p class="kdoc-guide-step__body"><?= htmlspecialchars($t['s4_body']) ?></p>
    <div class="kdoc-table-wrap">
        <table class="kdoc-table">
            <thead>
                <tr>
                    <th><?= htmlspecialchars($t['s4_table_col1']) ?></th>
                    <th><?= htmlspecialchars($t['s4_table_col2']) ?></th>
                    <th><?= htmlspecialchars($t['s4_table_col3']) ?></th>
                </tr>
            </thead>
            <tbody>
                <tr><td>Azure gpt-4o-mini ★</td><td>15–45 s</td><td>Fast drafts, most cases — default choice</td></tr>
                <tr><td>Azure gpt-4o</td><td>60–180 s</td><td>Complex multi-party cases requiring maximum depth</td></tr>
                <tr><td>GPU (cuttlefish)</td><td>30–90 s</td><td>Local inference, no Azure dependency</td></tr>
                <tr><td>Norwegian specialist (dbn-legal-agent) &#127475;&#127476;</td><td>40–90 s</td><td>Barneloven, barnevernsloven, and ECHR Art. 8 — tighter legal register</td></tr>
            </tbody>
        </table>
    </div>
</div>

<!-- Step 5: Corpus slices -->
<section class="kdoc-section--alt" id="s5">
<div class="kdoc-section">
    <h2 class="kdoc-guide-step__title"><?= htmlspecialchars($t['s5_title']) ?></h2>
    <p class="kdoc-guide-step__body"><?= htmlspecialchars($t['s5_body']) ?></p>
    <div class="kdoc-table-wrap">
        <table class="kdoc-table">
            <thead>
                <tr>
                    <th><?= htmlspecialchars($t['s5_table_col1']) ?></th>
                    <th><?= htmlspecialchars($t['s5_table_col2']) ?></th>
                    <th><?= htmlspecialchars($t['s5_table_col3']) ?></th>
                    <th><?= htmlspecialchars($t['s5_table_col4']) ?></th>
                </tr>
            </thead>
            <tbody>
                <tr><td><strong>Family Law Core</strong></td><td>ON</td><td>Barneloven, custody, samvær, mediation</td><td>Always — core for all cases</td></tr>
                <tr><td><strong>Child Welfare</strong></td><td>ON</td><td>Barnevern, omsorgsovertakelse, foster care</td><td>Always — core for all cases</td></tr>
                <tr><td><strong>ECHR</strong></td><td>ON</td><td>Art. 8 family life, Art. 9 religion, HUDOC vs Norway</td><td>Always — ECHR Art. 8 is central to most cases</td></tr>
                <tr><td>Hague Convention</td><td>OFF</td><td>INCADAT, cross-border abduction, wrongful removal</td><td>International child-abduction / relocation cases</td></tr>
                <tr><td>Norwegian Courts</td><td>OFF</td><td>Høyesterett + Lagmannsrett family decisions</td><td>When domestic appellate precedent is key</td></tr>
                <tr><td>Bufdir Guidance</td><td>OFF</td><td>Bufdir, Barneombudet, Statsforvalteren guidance</td><td>Cases involving procedural compliance by authorities</td></tr>
                <tr><td>Broader Legal Support</td><td>OFF</td><td>Arbeidsmiljøloven, NOUers, statutes, government background</td><td>Cases with employment, housing, or welfare angles</td></tr>
                <tr><td>DBN Resources</td><td>OFF</td><td>Do Better Norge guides, flashcards, resource directory</td><td>Supplement with lay-accessible DBN materials</td></tr>
            </tbody>
        </table>
    </div>
    <img src="assets/images/advocate/corpus-slices.png" alt="8 corpus slice toggles with ON/OFF state and upload zone" class="kdoc-screenshot" loading="lazy">
</div>
</section>

<!-- Step 6: Advanced controls -->
<div class="kdoc-section" id="s6">
    <h2 class="kdoc-guide-step__title"><?= htmlspecialchars($t['s6_title']) ?></h2>
    <p class="kdoc-guide-step__body"><?= htmlspecialchars($t['s6_body']) ?></p>
    <div class="kdoc-table-wrap">
        <table class="kdoc-table">
            <thead>
                <tr>
                    <th><?= htmlspecialchars($t['s6_table_col1']) ?></th>
                    <th><?= htmlspecialchars($t['s6_table_col2']) ?></th>
                    <th><?= htmlspecialchars($t['s6_table_col3']) ?></th>
                    <th><?= htmlspecialchars($t['s6_table_col4']) ?></th>
                </tr>
            </thead>
            <tbody>
                <tr><td><strong>Sub-questions</strong></td><td>3 – 5</td><td>4</td><td>Adversarial research angles generated per case. More = broader coverage, slower.</td></tr>
                <tr><td><strong>Chunks / sub-Q</strong></td><td>4 – 10</td><td>6</td><td>Corpus passages retrieved per sub-question before reranking.</td></tr>
                <tr><td><strong>Similarity floor</strong></td><td>0.20 – 0.60</td><td>0.30</td><td>Minimum similarity score for uploaded-doc chunks to be included.</td></tr>
                <tr><td><strong>Sources kept</strong></td><td>8 – 14</td><td>12</td><td>Top sources passed to synthesis after dedup and rerank.</td></tr>
                <tr><td><strong>Temperature</strong></td><td>0.05 – 0.40</td><td>0.15</td><td>Keep low (≤ 0.20) for grounded legal briefs; raise slightly for more creative framing.</td></tr>
            </tbody>
        </table>
    </div>
    <img src="assets/images/advocate/advanced-controls.png" alt="Advanced controls sliders and branching panel" class="kdoc-screenshot" loading="lazy">
</div>

<!-- Step 7: Upload -->
<section class="kdoc-section--alt" id="s7">
<div class="kdoc-section">
    <h2 class="kdoc-guide-step__title"><?= htmlspecialchars($t['s7_title']) ?></h2>
    <p class="kdoc-guide-step__body"><?= htmlspecialchars($t['s7_body']) ?></p>
    <p class="kdoc-guide-step__tip"><strong>&#128161;</strong> <?= htmlspecialchars($t['s7_tip']) ?></p>
</div>
</section>

<!-- Step 8: Preview angles -->
<div class="kdoc-section" id="s8">
    <h2 class="kdoc-guide-step__title"><?= htmlspecialchars($t['s8_title']) ?></h2>
    <p class="kdoc-guide-step__body"><?= htmlspecialchars($t['s8_body']) ?></p>
    <p class="kdoc-guide-step__tip"><strong>&#128161;</strong> <?= htmlspecialchars($t['s8_tip']) ?></p>
</div>

<!-- Step 9: Understanding output -->
<section class="kdoc-section--alt" id="s9">
<div class="kdoc-section">
    <h2 class="kdoc-guide-step__title"><?= htmlspecialchars($t['s9_title']) ?></h2>
    <p class="kdoc-guide-step__body"><?= htmlspecialchars($t['s9_body']) ?></p>

    <div class="kdoc-output-panels">
        <div class="kdoc-output-panel">
            <h3 class="kdoc-output-panel__title"><?= htmlspecialchars($t['s9_p1_title']) ?></h3>
            <p><?= htmlspecialchars($t['s9_p1_body']) ?></p>
        </div>
        <div class="kdoc-output-panel">
            <h3 class="kdoc-output-panel__title"><?= htmlspecialchars($t['s9_p2_title']) ?></h3>
            <p><?= htmlspecialchars($t['s9_p2_body']) ?></p>
        </div>
        <div class="kdoc-output-panel">
            <h3 class="kdoc-output-panel__title"><?= htmlspecialchars($t['s9_p3_title']) ?></h3>
            <p><?= htmlspecialchars($t['s9_p3_body']) ?></p>
        </div>
        <div class="kdoc-output-panel">
            <h3 class="kdoc-output-panel__title"><?= htmlspecialchars($t['s9_p4_title']) ?></h3>
            <p><?= htmlspecialchars($t['s9_p4_body']) ?></p>
        </div>
    </div>

    <div class="kdoc-gallery">
        <div class="kdoc-gallery__item">
            <img src="assets/images/advocate/output-brief.png" alt="Output — strongest arguments and advocate brief with citations" class="kdoc-screenshot" loading="lazy">
        </div>
        <div class="kdoc-gallery__item">
            <img src="assets/images/advocate/sub-questions.png" alt="Sub-question research trail with ECHR and uploaded document sources" class="kdoc-screenshot" loading="lazy">
        </div>
    </div>
</div>
</section>

<!-- Step 10: Counter-brief -->
<div class="kdoc-section" id="s10">
    <h2 class="kdoc-guide-step__title"><?= htmlspecialchars($t['s10_title']) ?></h2>
    <p class="kdoc-guide-step__body"><?= htmlspecialchars($t['s10_body']) ?></p>
    <img src="assets/images/advocate/output-next.png" alt="What remains uncertain, next practical step, and counter-brief prompt" class="kdoc-screenshot" loading="lazy">
</div>

<!-- Step 11: Tips -->
<section class="kdoc-section--alt" id="s11">
<div class="kdoc-section">
    <h2 class="kdoc-guide-step__title"><?= htmlspecialchars($t['s11_title']) ?></h2>
    <ul class="kdoc-tips">
        <li><?= htmlspecialchars($t['tip1']) ?></li>
        <li><?= htmlspecialchars($t['tip2']) ?></li>
        <li><?= htmlspecialchars($t['tip3']) ?></li>
        <li><?= htmlspecialchars($t['tip4']) ?></li>
        <li><?= htmlspecialchars($t['tip5']) ?></li>
        <li><?= htmlspecialchars($t['tip6']) ?></li>
    </ul>
</div>
</section>

<!-- Reasoning pipeline screenshot -->
<div class="kdoc-section">
    <p class="kdoc-section__eyebrow">Under the hood</p>
    <h2 class="kdoc-section__title">The 7-step reasoning pipeline — visible as it runs.</h2>
    <p class="kdoc-section__sub">Every step from query interpretation to citation confidence is logged in the Reasoning panel in real time. Nothing is hidden.</p>
    <img src="assets/images/advocate/reasoning-pipeline.png" alt="7-step reasoning panel showing pipeline steps completing in sequence" class="kdoc-screenshot" loading="lazy">
    <p style="text-align:center;margin-top:1rem;"><a href="/advocate-tech.php" class="kdoc-inline-link">Read the full architecture →</a></p>
</div>

<!-- CTA strip -->
<section class="kdoc-cta-strip">
    <h2 class="kdoc-cta-strip__title"><?= htmlspecialchars($t['cta_title']) ?></h2>
    <p class="kdoc-cta-strip__sub"><?= htmlspecialchars($t['cta_sub']) ?></p>
    <div class="kdoc-hero__ctas">
<?php if ($isAuthed): ?>
        <a href="/advocate.php" class="kdoc-btn-primary"><?= htmlspecialchars($t['btn_open']) ?></a>
<?php else: ?>
        <a href="<?= htmlspecialchars($toolsLogin) ?>" class="kdoc-btn-primary"><?= htmlspecialchars($t['btn_signin_cta']) ?></a>
        <a href="<?= htmlspecialchars($registerUrl) ?>" class="kdoc-btn-secondary"><?= htmlspecialchars($t['btn_register']) ?></a>
<?php endif; ?>
    </div>
</section>

<?php require_once __DIR__ . '/includes/footer.php'; ?>
<script src="assets/js/tools.js" defer></script>
</body>
</html>
