Amvionlie CMS

Amvionlie CMS

Internal Docs

Addon Governance - Internal Docs • Updated 2026-04-15 15:29:18

Amvionlie CMS

Temporary Internal Docs Addon Specification

Document Type: Build Specification
Status: Approved, Updated After Initial Build Pass
Date: 2026-04-15

Purpose

This document defines the Temporary Internal Docs addon for Amvionlie CMS.

Its purpose is to give the project a controlled internal place to store, edit, organize, read, archive, and manage development documentation inside the CMS during active system build work.

This addon exists to solve the current source material and handoff problem during development.

It is not intended to become the final Wiki.
It is not intended to become the Pages system.
It is not intended to become a reusable documentation engine.
It is not intended to become a visual builder.
It is not intended to become a permanent product feature.

It is a temporary internal project utility.

Once the real Wiki or final documentation platform exists, this addon may be retired and removed.

Core Intent

This addon exists so project source material can live inside Amvionlie instead of relying on limited chat uploads and fragmented handoff between sessions.

It must allow project documents to be pasted into the CMS, stored as markdown or plain text, edited later, organized simply, read easily, and archived when replaced.

This addon exists to support active development work such as:

  • project architecture documents
  • governance documents
  • authority documents
  • addendums
  • changelogs
  • issue logs
  • planning notes
  • implementation notes
  • handoff notes between chat sessions

This addon is disposable by design.

What This Addon Is

This addon is:

  • a temporary internal documentation manager
  • a markdown-first text storage and reading tool
  • a simple admin authoring system
  • a controlled source library for active project documents
  • a lightweight internal frontend reading surface for approved active documents
  • a temporary project document access surface for ChatGPT-assisted development work

What This Addon Is Not

This addon is not:

  • a Page Builder
  • a Layout Builder
  • a block editor
  • a media system
  • a final Wiki
  • a final public documentation portal
  • a reusable knowledge base product
  • a permanent system foundation addon

If work begins pushing it toward any of those roles, the direction is wrong.

Build Philosophy Rule

This addon must be built complete within its approved scope.

That means no fake placeholders presented as finished, no half implementation sold as complete, and no skipping required system parts just to get one screen working.

A complete first version means the addon includes its full approved data model, routes, admin flows, rendering flow, archive handling, status handling, visibility handling, and permissions required for normal use.

This addon must still remain intentionally small.

Complete does not mean bloated.
Complete means nothing required by this document is missing.

Current Build Reality

The addon now has a working initial implementation with the following completed behavior:

  • create document flow
  • edit document flow
  • admin read view
  • admin delete confirmation view
  • archive flow
  • restore flow
  • delete flow
  • slug auto-generation while typing
  • markdown and plain text rendering support
  • admin list filters and sorts
  • frontend document route
  • frontend document rendering inside the active template shell
  • global addon-level frontend exposure toggle
  • document-level visibility toggle from the list view
  • working delete redirect back to list
  • working frontend route parameter handoff for named slug routes

The addon is usable now.

It is not finished relative to the broader organization goals below.

Required First Version Scope

The first full version must include all of the following:

  • document title
  • document slug
  • document body
  • content format support for markdown and plain text
  • simple document type or grouping field
  • status field
  • visibility field
  • archive behavior through status handling
  • list view
  • create view
  • edit view
  • read or view screen in admin
  • frontend read flow for allowed active public documents
  • restore flow for archived documents
  • delete flow
  • basic filtering by status
  • basic sorting by newest updated and newest created
  • minimal permissions for its own management flows

No builder system is required.
No revision history is required.
No media system is required.
No advanced workflow engine is required.

Content Format Rule

This addon must support both markdown and plain text.

Markdown is the primary format.

Plain text must also be supported so the user is not forced into markdown for every document.

The addon must store the chosen format explicitly so rendering behavior remains truthful and deterministic.

Supported initial formats:

  • markdown
  • plain_text

No visual page construction is required.

Editor Rule

A basic editor is sufficient.

A plain textarea is acceptable and preferred for version one.

If a richer editor is already easy to wire safely, it may be considered later, but this addon must not depend on complex editor behavior to be usable.

The priority is fast paste, save, edit, and read.

Status Rule

Status and visibility must remain separate.

Required status values:

  • draft
  • active
  • archived

Draft

Draft means the document is not ready for working reference.

Draft documents remain admin-only.

Draft documents must never appear in frontend.

Active

Active means the document is a current working reference.

Active documents may be exposed in frontend only if their visibility also allows it and the addon frontend is globally enabled.

Archived

Archived means the document is retained for admin history and reference only.

Archived documents remain readable in admin.

Archived documents must never appear in frontend, regardless of visibility.

Archived documents must not be treated as current working source material.

Visibility Rule

Visibility must remain simple.

Required visibility values:

  • public
  • private

Visibility controls whether an active document may be exposed in frontend reading flow when the addon frontend is globally enabled.

Visibility does not override status.

That means:

  • active + public + frontend enabled = may appear in frontend
  • active + private + frontend enabled = admin-only
  • draft + public = still not frontend
  • archived + public = still not frontend
  • frontend disabled = no frontend docs available at all

Archived and draft documents must stay out of frontend.

Global Frontend Exposure Rule

This addon now requires a simple addon-level frontend exposure switch.

Its purpose is not detailed permissions logic.
Its purpose is to let the user expose Internal Docs to frontend while working with ChatGPT and hide the entire frontend surface when not working.

Required behavior:

  • frontend enabled = eligible public active documents may be reached
  • frontend disabled = all frontend document routes fail safely
  • this toggle must be simple and admin-controlled
  • this toggle must not require Permissions Manager expansion for now

This is intentionally temporary and practical.

Archive Rule

Archive is required in version one.

Archive is not deletion.

Archive is a retained state used to keep older or replaced documents available to admins while removing them from the active working set.

Required archive behavior:

  • admin can archive a document
  • admin can view archived documents
  • admin can restore an archived document
  • archived documents are excluded from normal frontend reading flow
  • archived documents are clearly identifiable in admin views
  • archived documents can still be deleted if the user chooses

Archive exists specifically to reduce drift while preserving temporary historical reference.

Organization Rule

The addon currently includes one lightweight organization field:

  • document_group

This is currently a free-text grouping value.

That implementation is acceptable only as the current temporary state.

It is not the intended long-term working structure for this addon if the document library continues to grow heavily.

Current Organization Limitation

The current document_group field behaves like a tag field, not a true managed category system.

That creates these problems:

  • duplicate naming drift
  • spelling inconsistency
  • weak discovery
  • poor large-scale browsing
  • no direct category pages
  • no clean project-wide document access surface for ChatGPT

For a small document set this is tolerable.
For a large document set it is not.

Planned Category Direction

The next approved direction for this addon is to replace loose group text with real managed categories.

Planned category goals:

  • create categories as real records
  • assign documents to categories from a controlled list
  • give each category its own linkable page
  • use categories as the primary browsing surface
  • reduce reliance on one giant document list
  • make it easier for ChatGPT to access project document collections by topic

Nested categories are not required.
Advanced taxonomy is not required.
This must remain flat and simple.

Slug Rule

Each document must have a readable slug.

The slug should auto-fill from the title and remain editable.

Slug uniqueness must be enforced.

This follows the normal Amvionlie admin pattern.

Current implemented behavior:

  • slug auto-populates while typing the title
  • slug generation uses the document UUID fragment
  • slug remains editable
  • uniqueness is enforced on save

Search Rule

Basic search is allowed in version one and recommended.

It may be limited to:

  • title
  • slug
  • document_group

Full body search is not required for the first version.

If body search is added later, it must be approved separately.

Sorting and Filtering Rule

The list view must support practical working filters and sorts.

Required filters:

  • all
  • draft
  • active
  • archived
  • public
  • private

Required sorts:

  • newest updated
  • oldest updated
  • newest created
  • oldest created
  • title A to Z
  • title Z to A

This is enough for the first version.

Frontend Rule

This addon may expose a simple frontend reading flow for internal working use.

It does not need a polished public product experience.

The frontend output may remain basic and text-first.

Frontend eligibility rules:

  • only active documents may appear in frontend
  • active documents must also be public
  • the addon frontend must also be globally enabled
  • draft documents must never appear in frontend
  • archived documents must never appear in frontend

The frontend reading flow must load inside the active site template shell, specifically through the template page rendering path and into the main content region.

Bare output outside the template shell is not acceptable as the intended final behavior.

This addon is not responsible for public theme complexity.

It only needs a safe readable output inside the existing frontend template framework.

Frontend Access Use Case Rule

One of the practical purposes of this addon is to let ChatGPT read project documents from Amvionlie without relying on scattered chat uploads.

That means the addon must support a usable document access pattern for project work.

The current direct document route is acceptable for individual documents.

However, broader grouped access requires category-level browsing so the user does not need to hand over dozens of separate links for one project area.

Ownership Rule

This addon owns only its own documentation records, its own settings, and its own management UI.

It does not own:

  • Pages
  • Wiki
  • Media
  • Layout Builder
  • Template rendering architecture
  • Theme rendering architecture
  • global routing ownership outside its own routes
  • global permissions definitions outside its own required permissions
  • project architecture outside the text stored in its own records

This addon is a temporary internal docs store only.

Permissions Rule

Permissions must remain minimal and addon-owned.

Required permission capabilities for version one:

  • internal_docs.view
  • internal_docs.create
  • internal_docs.edit
  • internal_docs.delete
  • internal_docs.archive
  • internal_docs.restore
  • internal_docs.publish

These govern addon management behavior only.

Visibility is not a replacement for permissions.

The current global frontend exposure switch is intentionally separate from Permissions Manager expansion.

Failure Rule

If this addon fails:

  • Core must continue running
  • Admin must continue running
  • unrelated addons must continue running
  • frontend must fail safely for this addon only
  • broken documents must not break the rest of the site

A bad document must not become a system-wide failure.

Deletion and Replaceability Rule

This addon must stay easy to remove later.

Its data and logic must remain isolated.

It must not spread hidden dependency across unrelated systems.

Nothing outside this addon should become dependent on it as a permanent foundation.

When the real Wiki or final documentation system exists, this addon should be removable with normal lifecycle handling.

Database Schema

The current working build uses one document table and one addon settings table.

Owned Tables

amvinternaldocs

Primary document storage table.

amvinternaldocs_settings

Simple addon-owned settings table for temporary addon behavior, currently used for frontend exposure control.

These tables are owned only by the Temporary Internal Docs addon.

Other systems may read through approved routes or future controlled integration, but they do not own this data.

Required Columns, amvinternaldocs

internaldocuuid
Primary UUID for the document.

title
Human-readable document title.

slug
Unique readable slug.

body
Stored document content.

content_format
Allowed values:

  • markdown
  • plain_text

document_group
Current temporary organization field.

status
Allowed values:

  • draft
  • active
  • archived

visibility
Allowed values:

  • public
  • private

sort_order
Optional manual display order support. Default 0.

createdbyuser_uuid
UUID of the creating user, nullable if unavailable during imports.

updatedbyuser_uuid
UUID of the most recent editing user, nullable if unavailable.

createdbyname
Human-readable creator name snapshot.

updatedbyname
Human-readable updater name snapshot.

created_at
Creation timestamp.

updated_at
Last update timestamp.

Required Columns, amvinternaldocs_settings

setting_key
Primary settings key.

setting_value
Stored settings value.

updated_at
Last update timestamp.

Current Required Setting Keys

frontend_enabled
Simple toggle value.
Expected values:

  • 1
  • 0

Required Index and Constraint Direction

The schema should include at minimum:

  • primary key on internaldocuuid
  • unique key on slug
  • index on status
  • index on visibility
  • index on document_group
  • index on created_at
  • index on updated_at
  • optional combined index on status + visibility for frontend filtering
  • primary key on amvinternaldocssettings.settingkey

Schema Notes

The schema must remain intentionally small.

No revision table is required.
No version history table is required.
No media relation table is required.
No taxonomy bridge tables are required yet.
No custom field tables are required.

If real categories are added next, that requires explicit schema expansion for category ownership.

File and Folder Structure

The addon follows normal Amvionlie addon structure and remains self-contained.

Required Addon Path

addons/internal_docs/

Current Required Structure

addons/
└── internal_docs/
    ├── index.php
    ├── manifest.php
    ├── bootstrap/
    │   ├── index.php
    │   └── install_contract.php
    ├── controllers/
    │   ├── index.php
    │   ├── list.php
    │   ├── create.php
    │   ├── edit.php
    │   ├── view.php
    │   ├── archive.php
    │   ├── restore.php
    │   ├── delete.php
    │   ├── public_view.php
    │   ├── frontend_toggle.php
    │   └── visibility_toggle.php
    ├── database/
    │   ├── index.php
    │   ├── install.php
    │   ├── rollback.php
    │   └── upgrade.php
    ├── languages/
    │   ├── index.php
    │   └── en_US/
    │       ├── index.php
    │       └── internal_docs.php
    ├── runtime/
    │   ├── index.php
    │   ├── internal_doc_service.php
    │   ├── internal_doc_repository.php
    │   ├── internal_doc_validator.php
    │   ├── internal_doc_slug_service.php
    │   └── internal_doc_render_service.php
    └── views/
        ├── index.php
        ├── admin/
        │   ├── index.php
        │   ├── list.php
        │   ├── create.php
        │   ├── edit.php
        │   ├── view.php
        │   ├── delete.php
        │   └── inc/
        │       ├── index.php
        │       ├── document_form.php
        │       └── document_table.php
        └── public/
            ├── index.php
            └── view.php

File Structure Responsibilities

manifest.php

Declares addon identity, metadata, routes, permissions, and lifecycle requirements.

bootstrap/install_contract.php

Defines installer-facing contract requirements for this addon.

controllers/list.php

Admin list view with filtering, sorting, and frontend exposure state display.

controllers/create.php

Create flow for new documents.

controllers/edit.php

Edit flow for existing documents.

controllers/view.php

Admin read view.

controllers/archive.php

Moves a document to archived status.

controllers/restore.php

Restores an archived document to a non-archived working state.

controllers/delete.php

Deletes a document.

controllers/public_view.php

Frontend read controller for active public documents only when addon frontend exposure is enabled.

controllers/frontend_toggle.php

Admin toggle handler for addon-level frontend exposure.

controllers/visibility_toggle.php

Admin toggle handler for per-document public and private visibility from list view.

database/install.php

Creates the addon-owned tables and required indexes.

database/rollback.php

Drops or safely reverses install actions if installation fails.

database/upgrade.php

Handles future controlled schema upgrades if ever needed.

runtime/internaldocservice.php

Main business logic service for create, update, archive, restore, delete, settings behavior, and frontend eligibility rules.

runtime/internaldocrepository.php

Database read and write access for internal docs records and addon settings.

runtime/internaldocvalidator.php

Input validation for title, slug, status, visibility, content format, and read eligibility.

runtime/internaldocslug_service.php

Slug generation and uniqueness handling.

runtime/internaldocrender_service.php

Render-safe output for markdown and plain text.

views/admin/list.php

Admin list page with frontend exposure status and toggle.

views/admin/create.php

Admin create page.

views/admin/edit.php

Admin edit page.

views/admin/view.php

Admin read page.

views/admin/delete.php

Admin delete confirmation page.

views/admin/inc/document_form.php

Reusable form partial for create and edit.

views/admin/inc/document_table.php

Reusable list table partial and action surface.

views/public/view.php

Simple frontend read template for eligible documents.

Routing Direction

The addon needs both admin and public routes.

Current Admin Route Direction

  • /admin/internal-docs
  • /admin/internal-docs/create
  • /admin/internal-docs/edit
  • /admin/internal-docs/view
  • /admin/internal-docs/archive
  • /admin/internal-docs/restore
  • /admin/internal-docs/delete
  • /admin/internal-docs/frontend-toggle
  • /admin/internal-docs/visibility-toggle

Current Public Route Direction

  • /docs/{slug}

Public route access must still honor status, visibility, and global frontend exposure rules.

Admin UI Rule

The admin UI must remain very simple.

At minimum it should provide:

  • list page
  • create page
  • edit page
  • read page
  • archive action
  • restore action
  • delete action
  • status field
  • visibility field
  • content format field
  • grouping field
  • filtering and sorting support
  • global frontend exposure toggle
  • document visibility toggle in list view

The UI should prioritize speed and clarity.

The current document visibility button in the list should remain a direct visibility toggle, not a frontend link.

This is more human-manageable for a large document set.

Rendering Rule

Rendering must remain truthful to content format.

If content_format is markdown, render as markdown.
If contentformat is plaintext, render as escaped plain text with readable formatting.

The renderer must not guess the format.

The stored content_format field is authoritative.

Changelog Use Case Rule

This addon must be suitable for changelog use from day one.

That means it must be easy to:

  • create a new document quickly
  • update a document often
  • sort by updated date
  • archive old changelog or handoff records when replaced
  • keep working notes in a clean readable system

This is one of the primary reasons this addon exists.

Revision Rule

Revision history is not required for version one.

Archive support is sufficient for the current project phase.

If revision history is ever desired later, it requires explicit approval and a separate schema decision.

Media Rule

No media support is required.

This addon is text-first.

No uploads, gallery behavior, attachments, or embed management are part of version one.

Remaining Approved Work

The following work is still approved and still pending:

1. Real Categories

Replace the loose document_group pattern with real managed categories.

This includes:

  • category records
  • controlled category selection from a list
  • removal of free-text organization drift
  • human-manageable large-scale organization

2. Links to Categories

Categories must become browsable entry points.

This includes:

  • category routes
  • category read pages
  • category-level access paths suitable for project work with ChatGPT

3. Category Frontend Display

A category page must display the documents inside it in a clean usable way.

This includes:

  • document list inside the category
  • pagination for category document pages
  • useful list display structure
  • likely title plus short description or fallback preview
  • practical browsing for large groups

4. Admin Category-Centered Browsing

The top-level admin surface should move toward category-centered management rather than one endlessly growing flat list.

This includes the intended direction of:

  • main view showing categories
  • each category row showing document count
  • entering a category to see its document list
  • pagination where document volume requires it

This remains intentionally simple and must not become a full wiki feature set.

Recommended Build Direction From Here

The next phase should proceed as a small complete extension of the current addon with:

  • real categories
  • category routes
  • category pages
  • category document pagination
  • simple category-centered admin browsing
  • no nested category system
  • no advanced permissions expansion
  • no wiki-style feature growth

The addon must stay useful immediately and easy to remove later.

Future Conversion Rule

The intended lifecycle is:

  1. Use this addon during active Amvionlie development
  2. Store and maintain project source documents inside the CMS
  3. Archive older and replaced documents as rewrites happen
  4. Use frontend exposure only when working and disable it when not needed
  5. Move or rewrite important material into the real Wiki later
  6. Retire and remove this addon when no longer needed

That lifecycle is intentional and should guide the build.

Lock Intent

Until replaced by a newer approved document, the following rule must be treated as the intended direction for implementation:

The Temporary Internal Docs addon is a temporary markdown and plain text documentation manager for Amvionlie CMS. It exists only to store, edit, organize, read, archive, restore, and manage internal project documents during active CMS development. It is not a Page Builder, not a Wiki, not a final documentation product, and not a reusable content engine. The current build includes one owned document table, one owned settings table, admin create, edit, list, read, archive, restore, delete, and delete-confirmation flows, a simple frontend read path for active public documents, support for markdown and plain text, slug auto-generation, global frontend exposure control, and document-level public or private visibility toggling. The next approved work is to replace loose grouping with real categories, expose categories through linkable pages, and build clean category display behavior with pagination. Archived documents must remain admin-accessible but must never appear in frontend.