Skills definition overhaul & admin tool (#617)

# Description

Converts skills and professions from hardcoded Go definitions into a fully data-driven, YAML-backed system. Skills and professions are now loaded from datafiles at boot, can be hot-reloaded in-game, and are fully manageable through new admin UI pages and a CRUD API. The change removes the compiled-in skill constants in favor of plain lowercase string ids, with per-skill max levels and a generalized progression model.

## Changes

- Move skill and profession definitions out of Go and into per-entry YAML datafiles under `_datafiles/world/{default,empty}/skills/` and `/professions/`, loaded at server boot (skills first so professions can cross-reference).
- Replace compiled-in skill-name constants (`SkillTag`) with plain lowercase string ids referenced directly throughout commands, combat, and scripting.
- Add per-skill `maxlevel` (default 4) with progression math generalized to `max*(max+1)/2` skill points.
- Adopt a "reject writes, zero reads" validation policy: unknown skill ids warn and no-op on write, return 0 on read, so orphaned save entries stay inert and no save migration is needed.
- Restructure the `internal/skills` package into `skill.go`, `profession.go`, and `admin.go`, with new tests and test-data seeding helpers.
- Add admin pages for skills, professions, and API docs (`/admin/skills`, `/admin/skills-professions`, `/admin/skills-api`) plus admin navigation entries.
- Add a CRUD API for skills and professions (`/admin/api/v1/skills`, `/admin/api/v1/professions`) including per-entry YAML endpoints, gated behind a new `skills.write` permission.
- Support in-game hot-reload via `reload skills`.
- Add `internal/skills/README.md` and `AGENTS.md` documenting the data model, progression, philosophy, and working rules.

Author: Volte6

_datafiles/html/admin/skills-api.html

@@ -0,0 +1,315 @@
+{{template "header" .}}
+
+<style>
+    h1 { font-size: 1.5rem; margin-bottom: 0.25rem; }
+    .subtitle { color: var(--color-text-muted); margin-bottom: 1.5rem; font-size: 0.9rem; }
+
+    .page-layout { display: grid; grid-template-columns: 260px 1fr; gap: 1.25rem; align-items: start; }
+    @media (max-width: 800px) { .page-layout { grid-template-columns: 1fr; } }
+
+    .sidebar { background: var(--color-surface-white); border: 1px solid var(--color-border); border-radius: 6px; overflow: hidden; display: flex; flex-direction: column; }
+    .sidebar-header { padding: 0.75rem 0.9rem; border-bottom: 1px solid var(--color-border-light); }
+    .sidebar-header input[type="search"] { width: 100%; padding: 0.35rem 0.6rem; border: 1px solid var(--color-border-medium); border-radius: 4px; font-size: 0.85rem; }
+    .entity-list { overflow-y: auto; max-height: 72vh; }
+    .entity-row {
+        padding: 0.5rem 0.9rem; cursor: pointer; border-bottom: 1px solid var(--color-border-faint);
+        display: flex; align-items: baseline; gap: 0.5rem; font-size: 0.875rem;
+    }
+    .entity-row:last-child { border-bottom: none; }
+    .entity-row:hover { background: var(--color-row-hover); }
+    .entity-row.active { background: var(--color-primary); color: var(--color-surface-white); }
+    .entity-id { font-size: 0.75rem; color: var(--color-text-secondary); font-family: monospace; flex-shrink: 0; }
+    .entity-row.active .entity-id { color: var(--color-active-id); }
+    .no-entities { padding: 1.5rem; text-align: center; color: var(--color-text-faint); font-size: 0.85rem; }
+    .btn-new { margin: 0.6rem 0.9rem; padding: 0.4rem 0.9rem; border: none; border-radius: 4px; background: var(--color-success-text); color: var(--color-surface-white); font-size: 0.85rem; font-weight: 600; cursor: pointer; display: block; text-align: center; }
+    .btn-new:hover { background: var(--color-btn-new-hover); }
+
+    .editor-panel { background: var(--color-surface-white); border: 1px solid var(--color-border); border-radius: 6px; padding: 1.25rem; }
+    .editor-placeholder { color: var(--color-text-placeholder); text-align: center; padding: 4rem 1rem; font-size: 0.9rem; }
+
+    .status-bar { display: none; padding: 0.55rem 0.9rem; border-radius: 4px; font-size: 0.85rem; margin-bottom: 1rem; }
+    .status-bar.success { background: var(--color-success-bg); color: var(--color-success-text); display: block; }
+    .status-bar.error   { background: var(--color-error-bg); color: var(--color-error-text); display: block; }
+
+    .form-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 0.85rem 1.25rem; }
+    .form-grid .span2 { grid-column: 1 / -1; }
+    .field label { display: block; font-size: 0.78rem; font-weight: 600; color: var(--color-text-muted); margin-bottom: 0.25rem; text-transform: uppercase; letter-spacing: 0.03em; }
+    .field input[type="text"], .field textarea {
+        width: 100%; padding: 0.4rem 0.6rem; border: 1px solid var(--color-border-medium); border-radius: 4px;
+        font-size: 0.875rem; font-family: inherit; background: var(--color-surface-white);
+    }
+    .field input:focus, .field textarea:focus { outline: 2px solid var(--color-primary); outline-offset: 1px; border-color: transparent; }
+    .field input[readonly] { background: var(--color-surface-alt); color: var(--color-text-muted); cursor: not-allowed; }
+    .field textarea { resize: vertical; min-height: 70px; }
+    .field-hint { font-size: 0.75rem; color: var(--color-text-faint); margin-top: 0.2rem; }
+
+    .section-title { font-size: 0.78rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em; color: var(--color-text-subtle); padding: 0.75rem 0 0.4rem; border-bottom: 1px solid var(--color-border-light); margin-bottom: 0.75rem; grid-column: 1 / -1; }
+
+    .slots-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(130px, 1fr)); gap: 0.4rem; grid-column: 1 / -1; }
+    .slot-item {
+        display: flex; align-items: center; justify-content: center;
+        gap: 0.4rem; font-size: 0.82rem; font-weight: 500;
+        padding: 0.4rem 0.5rem; border-radius: 5px; cursor: pointer;
+        border: 1px solid var(--color-border); background: var(--color-surface-alt); color: var(--color-text-tertiary);
+        user-select: none; transition: background 0.12s, color 0.12s, border-color 0.12s;
+    }
+    .slot-item:hover { border-color: var(--color-text-placeholder); background: var(--color-border-faint); }
+    .slot-item input[type="checkbox"] { display: none; }
+    .slot-item.enabled {
+        background: var(--color-primary); color: var(--color-surface-white); border-color: var(--color-primary);
+    }
+
+    .btn-row { display: flex; gap: 0.6rem; margin-top: 1.25rem; grid-column: 1 / -1; }
+    .btn-save { padding: 0.45rem 1.2rem; background: var(--color-primary); color: var(--color-surface-white); border: none; border-radius: 4px; font-size: 0.875rem; font-weight: 600; cursor: pointer; }
+    .btn-save:hover { background: var(--color-primary-hover); }
+    .btn-delete { padding: 0.45rem 1rem; background: var(--color-surface-white); color: var(--color-error-text); border: 1px solid var(--color-btn-delete-border); border-radius: 4px; font-size: 0.875rem; font-weight: 600; cursor: pointer; }
+    .btn-delete:hover { background: var(--color-error-bg); }
+</style>
+<h1>Professions</h1>
+<p class="subtitle">View, create, edit and delete profession definitions. See the <a href="/admin/skills-api">API reference</a>.</p>
+
+<div class="page-layout">
+    <div class="sidebar">
+        <div class="sidebar-header">
+            <input type="search" id="profSearch" placeholder="Search professions…" oninput="filterProfs()" />
+        </div>
+        <div id="profList" class="entity-list">
+            <div class="no-entities">Loading…</div>
+        </div>
+        <button class="btn-new" onclick="newProf()">+ New Profession</button>
+    </div>
+
+    <div class="editor-panel">
+        <div id="editorPlaceholder" class="editor-placeholder">Select a profession to edit, or click "New Profession".</div>
+        <div id="editorForm" style="display:none">
+            <div id="statusBar" class="status-bar"></div>
+            <div class="form-grid">
+                <div style="grid-column:1/-1;display:flex;align-items:baseline;gap:0.75rem;margin-bottom:0.25rem">
+                    <p class="section-title" id="editorTitle" style="margin:0;flex:1">Edit Profession</p>
+                    <button class="yaml-badge" id="yaml-view-btn" style="display:none" onclick="showYamlModal(this.dataset.url,'Profession YAML')">YAML</button>
+                </div>
+
+                <div class="field">
+                    <label for="fProfId">Profession ID</label>
+                    <input type="text" id="fProfId" placeholder="treasure hunter" />
+                    <div class="field-hint">Lowercase, spaces allowed. Immutable after creation.</div>
+                </div>
+                <div class="field">
+                    <label for="fName">Name</label>
+                    <input type="text" id="fName" placeholder="Treasure Hunter" />
+                </div>
+
+                <div class="field span2">
+                    <label for="fDesc">Description</label>
+                    <textarea id="fDesc" rows="2" placeholder="A description of this profession."></textarea>
+                </div>
+
+                <div class="section-title">Skills</div>
+                <div class="field-hint span2" style="grid-column:1/-1; margin-bottom:0.5rem;">Click a skill to toggle it. Highlighted skills belong to this profession.</div>
+                <div class="slots-grid" id="skillsGrid"></div>
+
+                <div class="btn-row">
+                    <button class="btn-save" onclick="saveProf()">Save</button>
+                    <button class="btn-delete" id="btnDelete" onclick="deleteProf()" style="display:none">Delete</button>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+
+<script>
+let profsData = {};   // id(string) -> Profession
+let allSkillIds = []; // sorted skill ids
+let activeProfId = null;
+let isNew = false;
+
+async function loadProfs() {
+    const [res, skillsRes] = await AdminAPI.all([
+        AdminAPI.get('/admin/api/v1/professions'),
+        AdminAPI.get('/admin/api/v1/skills'),
+    ]);
+    if (!res.ok) { console.error('Failed to load professions:', res.error); return; }
+    profsData = (res.data && res.data.data) || {};
+    if (skillsRes.ok) {
+        const skillsMap = (skillsRes.data && skillsRes.data.data) || {};
+        allSkillIds = Object.keys(skillsMap).sort();
+        buildSkillsGrid();
+    }
+    renderList();
+    const hashId = decodeURIComponent(location.hash.slice(1));
+    if (hashId && profsData[hashId]) selectProf(hashId);
+}
+
+function filterProfs() {
+    const q = document.getElementById('profSearch').value.toLowerCase();
+    document.querySelectorAll('.entity-row').forEach(row => {
+        const name = (row.dataset.name || '').toLowerCase();
+        row.style.display = name.includes(q) ? '' : 'none';
+    });
+}
+
+function renderList() {
+    const list = document.getElementById('profList');
+    const ids = Object.keys(profsData).sort();
+    if (ids.length === 0) {
+        list.innerHTML = '<div class="no-entities">No professions found.</div>';
+        return;
+    }
+    list.innerHTML = ids.map(id => {
+        const p = profsData[id];
+        return `<div class="entity-row" data-id="${escAttr(id)}" data-name="${escAttr(id + ' ' + (p.Name || ''))}"
+            onclick="selectProf('${escAttr(id)}')">
+            <span>${escHtml(p.Name || id)}</span>
+        </div>`;
+    }).join('');
+    if (activeProfId !== null) highlightRow(activeProfId);
+}
+
+function highlightRow(id) {
+    document.querySelectorAll('.entity-row').forEach(r => r.classList.remove('active'));
+    const row = document.querySelector(`.entity-row[data-id="${cssEsc(id)}"]`);
+    if (row) row.classList.add('active');
+}
+
+function selectProf(id) {
+    activeProfId = id;
+    isNew = false;
+    location.hash = encodeURIComponent(id);
+    highlightRow(id);
+    populateForm(profsData[id]);
+}
+
+function newProf() {
+    activeProfId = null;
+    isNew = true;
+    document.querySelectorAll('.entity-row').forEach(r => r.classList.remove('active'));
+    populateForm(null);
+}
+
+function buildSkillsGrid() {
+    const grid = document.getElementById('skillsGrid');
+    if (!grid) return;
+    grid.innerHTML = '';
+    for (const id of allSkillIds) {
+        const lbl = document.createElement('label');
+        lbl.className = 'slot-item';
+        lbl.setAttribute('onclick', 'toggleSkill(this)');
+        lbl.innerHTML = '<input type="checkbox" class="skill-cb" value="' + escAttr(id) + '" /> ' + escHtml(id);
+        grid.appendChild(lbl);
+    }
+}
+
+function toggleSkill(label) {
+    const cb = label.querySelector('.skill-cb');
+    cb.checked = !cb.checked;
+    label.classList.toggle('enabled', cb.checked);
+}
+
+function populateForm(prof) {
+    document.getElementById('editorPlaceholder').style.display = 'none';
+    document.getElementById('editorForm').style.display = '';
+    document.getElementById('statusBar').className = 'status-bar';
+    document.getElementById('statusBar').textContent = '';
+    document.getElementById('btnDelete').style.display = isNew ? 'none' : '';
+    document.getElementById('editorTitle').textContent = isNew ? 'New Profession' : `Edit: ${prof ? prof.Name : ''}`;
+
+    const idInput = document.getElementById('fProfId');
+    idInput.readOnly = !isNew;
+
+    var yamlBtn = document.getElementById('yaml-view-btn');
+    if (!isNew && activeProfId != null) {
+        yamlBtn.dataset.url = '/admin/api/v1/professions/' + encodeURIComponent(activeProfId) + '/yaml';
+        yamlBtn.style.display = '';
+    } else {
+        yamlBtn.style.display = 'none';
+    }
+
+    const p = prof || {};
+    idInput.value = p.ProfessionId || '';
+    document.getElementById('fName').value = p.Name || '';
+    document.getElementById('fDesc').value = p.Description || '';
+
+    const selected = new Set((p.Skills || []).map(s => s.toLowerCase()));
+    document.querySelectorAll('.skill-cb').forEach(cb => {
+        cb.checked = selected.has(cb.value);
+        cb.closest('.slot-item').classList.toggle('enabled', cb.checked);
+    });
+}
+
+function buildPayload() {
+    const skills = [];
+    document.querySelectorAll('.skill-cb:checked').forEach(cb => skills.push(cb.value));
+    return {
+        ProfessionId: document.getElementById('fProfId').value.trim().toLowerCase(),
+        Name:         document.getElementById('fName').value.trim(),
+        Description:  document.getElementById('fDesc').value.trim(),
+        Skills:       skills,
+    };
+}
+
+async function saveProf() {
+    const payload = buildPayload();
+    if (!payload.ProfessionId) { showStatus('error', 'Profession ID is required.'); return; }
+    if (!payload.Name) { showStatus('error', 'Name is required.'); return; }
+    if (payload.Skills.length === 0) { showStatus('error', 'Select at least one skill.'); return; }
+
+    let res;
+    if (isNew) {
+        res = await AdminAPI.post('/admin/api/v1/professions', payload);
+        if (res.ok && res.data && res.data.data) {
+            const id = res.data.data.ProfessionId;
+            profsData[id] = res.data.data;
+            activeProfId = id;
+            isNew = false;
+            location.hash = encodeURIComponent(id);
+            renderList();
+            populateForm(profsData[id]);
+            showStatus('success', `Profession "${id}" created.`);
+        } else {
+            showStatus('error', res.error || 'Save failed.');
+        }
+    } else {
+        res = await AdminAPI.patch(`/admin/api/v1/professions/${encodeURIComponent(activeProfId)}`, payload);
+        if (res.ok) {
+            profsData[activeProfId] = (res.data && res.data.data) || payload;
+            renderList();
+            highlightRow(activeProfId);
+            document.getElementById('editorTitle').textContent = `Edit: ${payload.Name}`;
+            showStatus('success', `Profession "${activeProfId}" saved.`);
+        } else {
+            showStatus('error', res.error || 'Save failed.');
+        }
+    }
+}
+
+async function deleteProf() {
+    if (activeProfId === null) return;
+    if (!confirm(`Delete profession "${activeProfId}"? This cannot be undone.`)) return;
+    const res = await AdminAPI.delete(`/admin/api/v1/professions/${encodeURIComponent(activeProfId)}`);
+    if (res.ok) {
+        delete profsData[activeProfId];
+        activeProfId = null;
+        history.replaceState(null, '', location.pathname + location.search);
+        renderList();
+        document.getElementById('editorForm').style.display = 'none';
+        document.getElementById('editorPlaceholder').style.display = '';
+    } else {
+        showStatus('error', res.error || 'Delete failed.');
+    }
+}
+
+function showStatus(type, msg) {
+    const bar = document.getElementById('statusBar');
+    bar.className = 'status-bar ' + type;
+    bar.textContent = msg;
+    if (type === 'success') setTimeout(() => { bar.className = 'status-bar'; }, 3000);
+}
+
+function escHtml(s) { return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;'); }
+function escAttr(s) { return String(s).replace(/"/g,'&quot;').replace(/'/g,'&#39;'); }
+function cssEsc(s) { return String(s).replace(/"/g,'\\"'); }
+
+loadProfs();
+</script>
+
+{{template "footer" .}}