Requirements and Specifications

Wiki Farm PARA Mode

Functional Requirements and Technical Specification

Document purpose: This specification defines the first implementation of the structured personal knowledge management ("PARA Wiki") mode for a MediaWiki-based wiki farm. It is intended to be sufficiently explicit for use by a software developer or coding AI.

Status: Draft implementation specification Version: 1.0 Target platform: MediaWiki with Cargo and custom extension code Primary design principle: Preserve normal MediaWiki behavior wherever practical, while adding an optional structured PKM mode.

---

1. Product Scope

1.1 Wiki Modes

When a user creates a new wiki, the system shall support a configurable Wiki Mode.

Initial supported modes:

Mode	Description
`standard`	Flexible MediaWiki experience with optional starter content. Structured PARA rules are not enforced.
`para`	Structured personal knowledge management mode inspired by PARA and extended with Page Type, Page Status, Areas, Projects, Topics, type-specific metadata, and topic-specific metadata.

The architecture shall allow additional modes to be introduced later without redesigning the page metadata model.

The selected Wiki Mode shall be stored at the wiki level, not page level.

The user-facing name shall be PARA Wiki, but documentation should describe it as "inspired by the PARA method" rather than implying that every feature is part of Tiago Forte's original PARA methodology.

---

2. Core Concepts

Every normal content page in PARA Wiki mode shall have:

• exactly one PageType
• exactly one PageStatus

A page may also have:

• zero or one ParentArea when PageType=Area
• zero or more RelatedAreas when PageType!=Area
• zero or more RelatedProjects
• zero or more RelatedTopics
• zero or more type-specific metadata fields
• zero or more topic-specific metadata fields

Conceptual definitions:

Dimension	User-facing question	Meaning
Type	How will I use this page?	The functional role of the page.
Status	Is it currently relevant/active?	The lifecycle state of the page.
Area	What ongoing part of my life does it support?	An ongoing responsibility, activity, or intentionally maintained domain.
Project	What outcome does it support?	A finite outcome or goal.
Topic	What is it about?	A subject used to connect related pages.

---

3. Page Types

The application shall initially support exactly six Page Types. Users shall not be able to create custom Page Types in version 1.

PageType	Description	Guidance
`Study`	Notes derived from a source or structured learning.	Knowledge being acquired from a particular source, class, book, course, lecture, etc.
`Journal`	Chronological experience or reflection.	What happened or what the user experienced.
`Idea`	A concept, conclusion, insight, or synthesized thought.	An understanding the user developed rather than merely collected.
`Project`	Information supporting an intended finite outcome.	Something the user is trying to complete.
`Area`	An ongoing part of life that the user maintains or develops.	An ongoing responsibility, activity, or domain without a defined end.
`Resource`	Information collected primarily for future reference.	Information likely to have more use in the future than at the time it is stored.

Recommended stable internal identifiers:

study
journal
idea
project
area
resource

---

4. Page Statuses

The application shall initially support three Page Status values:

inception
active
archived

Users shall not be able to create custom statuses in version 1.

PageType	Inception	Active	Archived
Study	No	Yes	Yes
Journal	No	Yes	Yes
Idea	No	Yes	Yes
Project	Yes	Yes	Yes
Area	Yes	Yes	Yes
Resource	No	Yes	Yes

Definitions:

Status	Meaning
`Inception`	Being considered or developed but not yet committed.
`Active`	Currently relevant, maintained, pursued, or available for normal use.
`Archived`	Retained but no longer active.

Status shall affect default inclusion in views, selectors, reports, workflows, and search filters.

Status shall not determine authorization, sharing, privacy, or security permissions.

Archived pages shall remain directly accessible to users who otherwise have permission to view them.

---

5. Area Model

5.1 Area Definition

An Area is an ongoing responsibility, activity, or something the user intentionally maintains or develops over time.

Examples include Personal, Family, Household, Learning, Career, Travel & Vacations, Hobbies, Photography, Cooking, and Fitness & Nutrition.

5.2 Parent Area

An Area page may have zero or one ParentArea.

A page whose PageType=Area shall not use RelatedAreas.

Examples:

Hobbies
  ParentArea = NULL

Photography
  ParentArea = Hobbies

Cooking
  ParentArea = Hobbies

Career
  ParentArea = NULL

Skills development
  ParentArea = Career

A top-level Area is defined as:

PageType = Area
ParentArea = NULL

The system shall prevent an Area from being its own parent and shall prevent circular Area relationships.

The Area hierarchy shall support an arbitrary practical depth unless implementation limitations require a documented maximum.

5.3 Related Areas

A non-Area page may have zero or more RelatedAreas.

Each value shall reference an existing page whose PageType=Area.

When assigning an Area through the UI, the default picker shall show active Area pages. The user may enable an option such as Include archived Areas.

The Area picker should display hierarchy where practical.

The system should recommend no more than three Related Areas per page but shall not enforce a hard maximum.

---

6. Project Model

A Project is a page whose PageType=Project.

A Project shall normally have at least one RelatedArea, although this shall be a quality warning rather than a hard validation rule.

A page may have zero or more RelatedProjects.

Each Related Project shall reference an existing page whose PageType=Project and is Active by default in selectors. The picker shall allow archived Projects to be included optionally.

The system shall prevent a Project page from assigning itself as a Related Project.

Project hierarchy / ParentProject is explicitly out of scope for version 1, but the schema shall not preclude adding it later.

---

7. Project-to-Area Defaulting

When a Project is assigned to a page:

1. Read the selected Project's RelatedAreas.
2. Add any missing Project Areas to the edited page's RelatedAreas.
3. Do not remove any existing Areas.
4. Allow the user to remove any newly added Areas before saving.
5. Once the page is saved, the values are independent.

This behavior is default copying, not dynamic inheritance.

If the Project's Areas change later, existing pages assigned to that Project shall not automatically change.

---

8. Topic Model

8.1 Topic Is Not a Page Type

Topic shall not be added as a seventh PageType. PageType answers How will I use this page? Topic answers What is this page about?

8.2 Topics as First-Class Classification Objects

Topics shall be first-class application objects.

Recommended implementation:

Topic:<TopicName>

using a dedicated MediaWiki namespace.

Examples:

Topic:Python
Topic:Programming
Topic:Freshman Courses
Topic:Rome

Topic namespace pages are classification/hub objects and are not ordinary PARA knowledge pages. Topic pages shall not require a PageType.

A Topic should support at least:

Field	Requirement
TopicName	Required, unique within the wiki
TopicStatus	Active or Archived
Description	Optional
RelatedTopics	Optional/future-safe
MetadataDefinition	Optional structured definition of topic-specific fields
CreatedAt	System managed
UpdatedAt	System managed

Version 1 may omit RelatedTopics and MetadataDefinition UI if necessary, but the data model should allow future implementation.

8.3 Related Topics

Normal content pages may have zero or more RelatedTopics.

Each Related Topic shall reference an existing Topic object. Default picker behavior shall show active Topics, with an option to include archived Topics.

The system should recommend no more than three Topics per page for simplicity but shall not enforce a hard maximum.

8.4 Topic Creation

The RelatedTopics control should allow selecting an existing Topic and optionally creating a new Topic inline, subject to permissions.

The system shall prevent accidental duplicate Topics caused only by case differences or excess whitespace, consistent with MediaWiki title behavior.

---

9. Topic-Specific Metadata

The architecture shall support topic-specific metadata.

For example, Topic:Book could define Author, ISBN, Publisher, and PublicationDate. Topic:Vehicle could define Make, Model, ModelYear, and VIN.

Topic metadata and entity/schema metadata may eventually become separate concepts. Version 1 should therefore implement topic-specific metadata modularly rather than permanently coupling metadata schemas to Topic processing.

Recommended abstraction:

MetadataDefinition
MetadataField
MetadataAssignment
MetadataValue

---

10. Type-Specific Metadata

Each Page Type may expose additional metadata. The following fields are illustrative rather than mandatory for version 1.

PageType	Possible metadata
Study	SourceType, SourceTitle, Author, Instructor, Institution, StartDate, EndDate, Progress, URL, ISBN
Journal	JournalDate, StartDate, EndDate, Location
Idea	IdeaDate, Confidence, SourcePages
Project	StartDate, TargetDate, CompletionDate, Outcome, Progress
Area	ReviewFrequency, LastReviewed
Resource	SourceURL, SourceDate, Author

Potential future Project Outcome values include completed, abandoned, and cancelled. Outcome shall remain separate from PageStatus.

The type-specific metadata subsystem shall be extensible without schema redesign.

---

11. Unclassified Page Rule

Every non-Area page should normally have at least one of RelatedAreas, RelatedProjects, or RelatedTopics.

This shall not be a hard save-time validation rule.

If all three are empty, the page shall be classified as Unclassified for quality/reporting purposes.

The page shall display a non-blocking notification such as:

This page is not currently associated with an Area, Project, or Topic.

The user's Status / Wiki Health page shall include an Unclassified Pages section and count.

Area pages are exempt from this rule.

---

12. Wiki Health / Status Page

PARA Wiki mode shall include a system-generated or extension-generated Status or Wiki Health page.

Minimum metrics:

Metric	Definition
Unclassified Pages	Non-Area pages with no Area, Project, or Topic
Active Projects Without Areas	Project pages with no RelatedAreas
Top-Level Areas	Active Area pages with ParentArea=NULL
Sub-Areas	Active Area pages with ParentArea set
Archived Pages	Count grouped by PageType
Areas With No Associated Content	Areas with no child Areas and no related pages
Active Projects With No Recent Activity	Optional if reliable activity logic is available

All metrics should link to filtered page lists.

---

13. Page Metadata UI

Recommended user-facing labels:

Type
Status
Parent Area
Related Areas
Related Projects
Topics

Recommended internal field names:

PageType
PageStatus
ParentArea
RelatedAreas
RelatedProjects
RelatedTopics

Do not use numbered fields such as Area1, Area2, Area3, Project1, etc.

For an Area page, show Type, Status, Parent Area, Related Projects if applicable, and Topics. Hide/disable Related Areas.

For a non-Area page, show Type, Status, Related Areas, Related Projects, and Topics. Hide Parent Area.

When PageType changes, the UI shall dynamically re-evaluate valid statuses and applicable fields.

---

14. Cargo Storage Model

Cargo shall be used for structured querying unless implementation testing identifies a technical blocker.

Recommended main table: WikiPages.

Illustrative schema:

{{#cargo_declare:
_table=WikiPages
|PageType=String
|PageStatus=String
|ParentArea=Page
|RelatedAreas=List (,) of Page
|RelatedProjects=List (,) of Page
|RelatedTopics=List (,) of Page
}}

Requirements:

• Store page names as Cargo Page values rather than integer IDs unless testing identifies a strong reason otherwise.
• Use Cargo List fields for RelatedAreas, RelatedProjects, and RelatedTopics.
• Use Cargo-supported list querying such as HOLDS rather than manually parsing comma-separated strings.
• Topic references using a dedicated namespace may be stored as full titles such as Topic:Python.
• Topic data should use a separate Cargo table such as Topics.
• Type-specific metadata may use separate Cargo tables rather than making the main table excessively wide.

---

15. Data Integrity Rules

Rule	Enforcement
PageType required	Hard
PageStatus required	Hard
PageStatus valid for PageType	Hard
Area has at most one ParentArea	Hard
Area cannot use RelatedAreas	Hard
Non-Area cannot use ParentArea	Hard
ParentArea references Area page	Hard
RelatedAreas reference Area pages	Hard
RelatedProjects reference Project pages	Hard
RelatedTopics reference Topic objects	Hard
Area cannot parent itself	Hard
Area hierarchy cannot contain cycles	Hard
Project cannot relate to itself	Hard
Non-Area should have Area, Project, or Topic	Warning
Project should have at least one Area	Warning
More than three Areas or Topics	Advisory only

Invalid metadata submitted through APIs or non-UI mechanisms shall be rejected consistently with UI validation.

---

16. Archived Object Behavior

Archived pages remain accessible.

Default behavior:

• exclude archived Areas from Area pickers
• exclude archived Projects from Project pickers
• exclude archived Topics from Topic pickers
• optionally exclude archived pages from default dashboards and views
• allow users to explicitly include archived content
• direct links to archived pages continue to work

Archived shall not mean deleted and shall not modify sharing/privacy permissions.

---

17. Search and Browse Behavior

PARA Wiki shall support filtering/browsing by PageType, PageStatus, Area, Project, and Topic.

Examples:

Active Study pages in Learning
Resources related to Plan Italy vacation
Pages about Python
Archived pages in Photography
Unclassified pages

Area browse pages should be able to derive and display child Areas, directly related pages, active Projects associated with the Area, and optionally descendant-Area content.

Project browse pages should display Project metadata, Related Areas, pages assigned to the Project, and status/outcome information when implemented.

Topic pages should display the Topic description, pages assigned to the Topic, counts by PageType, and derived related Areas and Projects.

---

18. Onboarding

When creating a PARA Wiki, onboarding should explain:

Type: How will I use this page?
Status: Is it currently relevant/active?
Area: What ongoing part of my life does it support?
Project: What outcome does it support?
Topic: What is it about?

The user may optionally import starter pages. Starter pages shall be selectable; users should not be forced to import the entire sample set.

All imported starter pages should default to PageStatus=Active unless explicitly defined otherwise.

---

19. Starter Page Dataset

PageName	PageType	ParentArea	RelatedAreas	RelatedProjects	RelatedTopics
Personal	Area
Long-term goals	Resource		Personal
Weekly tasks	Resource		Personal
Gift ideas	Resource		Personal
Daily Journal	Journal		Personal
Fitness & Nutrition	Area
Tips for healthy eating	Resource		Fitness & Nutrition
Yoga	Area	Fitness & Nutrition
Why yoga helps me	Idea		Fitness & Nutrition
Household	Area
Products	Resource		Household
Household Technology	Resource		Household
Subscriptions	Resource		Household
Family	Area
Family traditions	Resource		Family
Family tree	Resource		Family
Friends & Social Activities	Area
Poker night planning	Resource		Friends & Social Activities
Why Small Gatherings Are More Enjoyable	Idea		Friends & Social Activities
Volunteering	Area
Past volunteering	Resource		Volunteering
Volunteering opportunities	Resource		Volunteering
Vehicles	Area
Honda Accord 2025	Resource		Vehicles
Vehicles being considered for purchase	Resource		Vehicles
Learning	Area
List of schools & courses attended	Resource		Learning
List of books I have read	Resource		Learning
Intro to Python	Study		Learning, Career	Complete course on Python	Programming, Python
Psychology 103	Study		Learning	University Degree	Freshman Courses
Music Theory 202	Study		Learning	University Degree	Freshman Courses
Travel & Vacations	Area
Bucket list	Resource		Travel & Vacations
Past vacations	Resource		Travel & Vacations
Spain Vacation Journal	Journal		Travel & Vacations
Travel loyalty programs	Resource		Travel & Vacations
Entertainment	Area
Concerts I might want to see	Resource		Entertainment
Concert Journal	Journal		Entertainment
Movies to rewatch	Resource		Entertainment
Hobbies	Area
Photography	Area	Hobbies
Canon EOS R10	Resource		Photography
Understanding Exposure by Bryan Peterson	Study		Photography
Tips for Low Light Photography	Resource		Photography
Cooking	Area	Hobbies
Career	Area
Skills development	Area	Career
Potential employers	Resource		Career
Create family vacation photo book	Project		Family, Photography
Replace kitchen floor	Project		Household
Plan Italy vacation	Project		Travel & Vacations, Family
Hotels in Rome	Resource		Travel & Vacations, Family	Plan Italy vacation
Complete course on Python	Project		Career, Learning
University Degree	Project		Learning

Required starter Topics if the corresponding starter pages are imported:

Programming
Python
Freshman Courses

Starter Project and Topic dependencies shall be handled automatically. No imported starter page may contain a dangling reference.

---

20. Page Creation Workflow

1. User enters page title.
2. User selects PageType.
3. System presents valid PageStatus values.
4. Default status should normally be Active.
5. If PageType=Area, show ParentArea and hide RelatedAreas.
6. Otherwise show RelatedAreas and hide ParentArea.
7. Show RelatedProjects.
8. Show RelatedTopics.
9. Load type-specific metadata fields.
10. Load topic-specific metadata fields as Topics are selected.
11. Validate hard rules.
12. Display advisory warnings separately.
13. Save page and structured metadata atomically where practical.

The system should minimize clicks and avoid repeated confirmation screens.

---

21. Editing Workflow

Existing metadata shall load into the editor.

Changing PageType shall re-evaluate valid statuses, update visible fields, warn before discarding invalid metadata, and never silently destroy user metadata.

Example: changing Area to Resource may safely offer to convert ParentArea to RelatedAreas. Changing Resource to Area with multiple RelatedAreas shall require the user to choose zero or one ParentArea.

---

22. Page Rename / Move Behavior

Because Page-valued metadata references page titles, page moves must preserve referential integrity.

The extension shall test MediaWiki/Cargo behavior for page moves. If Cargo does not automatically update references reliably, custom extension logic shall update ParentArea, RelatedAreas, RelatedProjects, and RelatedTopics as appropriate.

Topic page moves shall similarly update RelatedTopics references.

A maintenance script shall detect dangling references.

---

23. Page Delete Behavior

Deleting a referenced Area, Project, or Topic requires explicit handling.

Preferred behavior:

1. Display dependency count before deletion.
2. Provide links to referencing pages.
3. Do not silently remove relationship values.
4. Allow administrative forced deletion if MediaWiki permissions permit.
5. After deletion, Wiki Health shall identify dangling references until repaired.

Future enhancement: reassignment during deletion.

---

24. Permissions and Privacy

PARA classification is independent of access control.

Do not use PageStatus, PageType, Area, Project, or Topic as security boundaries.

All extension-generated lists and Cargo queries must respect MediaWiki read permissions and must not leak page titles or metadata for pages the viewer cannot access.

This applies to Area pages, Project pages, Topic pages, dashboards, autocomplete, selectors, API endpoints, counts, and search results.

---

25. API Requirements

The extension should expose structured operations through MediaWiki's API or a clearly defined REST interface.

Minimum operations:

Get page classification metadata
Set page classification metadata
List valid PageTypes
List valid statuses for a PageType
Search/select Areas
Search/select Projects
Search/select Topics
Create Topic
Get Wiki Health counts
List Unclassified pages

API validation rules shall match UI validation rules.

Example payload:

{
  "pageType": "study",
  "pageStatus": "active",
  "relatedAreas": ["Learning", "Career"],
  "relatedProjects": ["Complete course on Python"],
  "relatedTopics": ["Topic:Programming", "Topic:Python"]
}

---

26. Extension Architecture

Recommended implementation: one custom MediaWiki extension responsible for structured PKM behavior.

Working placeholder name: WikiFarmPKM.

Responsibilities:

• Wiki Mode configuration
• metadata validation
• metadata UI integration
• PageType/PageStatus rules
• Area hierarchy logic
• Project default-Area behavior
• Topic namespace behavior
• Cargo integration
• Wiki Health dashboard
• API endpoints
• maintenance scripts
• onboarding support hooks
• page move/delete consistency logic

Avoid scattering core business rules across templates, JavaScript snippets, and wiki pages. Templates may render data, but the extension should be the validation source of truth.

---

27. Configuration

Recommended wiki-level configuration:

$wgWikiFarmMode = 'para';

or an equivalent per-wiki application configuration.

Recommended configurable constants:

AllowedPageTypes
AllowedStatuses
StatusesByPageType
DefaultPageStatus
TopicNamespaceId
RecommendMaxAreas
RecommendMaxTopics
EnableProjectAreaDefaults
EnableWikiHealth

Do not hard-code numeric namespace IDs without a configuration constant.

---

28. Namespace Recommendation

Use a dedicated namespace:

Topic:

Do not place Topic hub pages in the main namespace.

Topic namespace pages should remain normal MediaWiki pages where practical so they retain revisions, watchability, linking, discussion, search, and history.

---

29. Query Examples

Conceptual Cargo queries:

RelatedAreas HOLDS 'Photography'

PageType='Project'
AND PageStatus='Active'
AND RelatedAreas HOLDS 'Family'

RelatedTopics HOLDS 'Topic:Python'

Unclassified conceptually means PageType is not Area and RelatedAreas, RelatedProjects, and RelatedTopics are all empty.

Implementation shall use exact Cargo syntax appropriate to the installed Cargo version.

---

30. Performance Requirements

Design for at least:

100,000 normal pages
10,000 Topics
10,000 Areas/Projects combined

without schema redesign.

Selectors/autocomplete must not load all matching objects into the browser. Use server-side search/autocomplete for large lists.

Wiki Health calculations should avoid expensive full scans on every page view. Acceptable approaches include cached counts, scheduled refresh, incremental updates on edit hooks, or indexed Cargo queries. The chosen approach shall be documented.

---

31. Accessibility and UX

All classification controls shall be keyboard accessible. Do not rely on color alone for status.

Multi-select fields should support typeahead search, keyboard selection, removal of values, and visible Area hierarchy where practical.

Warnings shall be clearly distinguishable from hard errors.

---

32. Logging and Auditability

Metadata changes should be visible in page revision history where practical.

At minimum, administrators should be able to determine who changed PageType, PageStatus, Area/Project/Topic relationships, and when.

Avoid storing critical classification changes only in mutable Cargo rows without corresponding revision/audit context.

---

33. Maintenance Scripts

Provide maintenance scripts for:

Rebuild Cargo PKM tables
Validate all PARA metadata
Detect invalid status/type combinations
Detect dangling Area references
Detect dangling Project references
Detect dangling Topic references
Detect Area hierarchy cycles
Rebuild Wiki Health data
Repair/reconcile metadata after page moves

Scripts should support dry-run mode where corrective behavior is possible.

---

34. Migration and Backward Compatibility

Standard Wiki pages shall not be forced into PARA metadata rules.

If a wiki changes from Standard to PARA mode, provide a migration/onboarding process rather than immediately invalidating all existing pages.

A migration condition such as Needs Classification should be a workflow/report state rather than necessarily a new PageStatus.

If a PARA Wiki changes to Standard mode, preserve existing structured metadata unless an administrator explicitly removes it.

---

35. Explicit Non-Goals for Version 1

Unless separately approved, version 1 does not include:

Custom user-defined PageTypes
Custom user-defined PageStatuses
ParentProject hierarchy
Automatic dynamic Area inheritance from Projects
AI-based automatic classification
Automatic Topic ontology generation
Security/ACL implementation based on PARA properties
Complex Topic-to-Topic ontology
Goal as a seventh PageType
Capture inbox implementation
Gamification beyond Wiki Health warnings/counts

The architecture should not unnecessarily prevent these future capabilities.

---

36. Acceptance Criteria

Scenario A: Create top-level Area

Create Hobbies with PageType=Area, PageStatus=Active, ParentArea=NULL.

Expected: save succeeds, Hobbies appears in Area selectors, and Hobbies appears under Top-Level Areas.

Scenario B: Create child Area

Create Photography with PageType=Area, PageStatus=Active, ParentArea=Hobbies.

Expected: save succeeds; hierarchy shows Hobbies -> Photography; Photography appears in RelatedAreas selectors; Photography has no RelatedAreas value.

Scenario C: Prevent invalid Area metadata

Attempt to save Photography as Area with RelatedAreas=Hobbies.

Expected: save rejected and user instructed to use ParentArea.

Scenario D: Study with multiple relationships

Create Intro to Python as Study/Active with Areas Learning and Career, Project Complete course on Python, and Topics Programming and Python.

Expected: all relationships persist and query correctly.

Scenario E: Project Area defaulting

Plan Italy vacation has Areas Travel & Vacations and Family. Assign it to Hotels in Rome.

Expected: both Areas are initially added. User may remove Family before saving. Later changes to Project Areas do not modify Hotels in Rome automatically.

Scenario F: Archive Area

Archive Photography.

Expected: existing references remain; it disappears from default picker; Include archived Areas reveals it; direct access still works.

Scenario G: Unclassified page

Create Resource with no Area, Project, or Topic.

Expected: save succeeds; warning appears; Wiki Health count increases; page appears in Unclassified list.

Scenario H: Invalid status

Attempt Resource + Inception.

Expected: save rejected.

Scenario I: Area cycle

Attempt Hobbies.ParentArea=Photography while Photography.ParentArea=Hobbies.

Expected: save rejected with clear cycle error.

Scenario J: Topic behavior

Create Topic:Python, assign it to several pages, then archive it.

Expected: Topic hub lists associated pages; active selector includes it before archive; default selector excludes it after archive; existing references remain intact.

---

37. Open Design Questions

The developer/coding AI shall not invent final behavior for these items without product approval:

1. Exact type-specific metadata fields for each PageType.
2. Exact topic-specific metadata definition format.
3. Whether Topic pages may themselves be assigned RelatedTopics.
4. Whether Area pages may have Topics and/or RelatedProjects. Current recommendation: yes.
5. Whether Project pages may have RelatedTopics. Current recommendation: yes.
6. Exact VisualEditor integration approach.
7. Whether classification metadata is stored in wikitext templates, a revision-backed slot/content model, or another revision-backed mechanism in addition to Cargo.
8. Whether Wiki Mode is fixed at creation or can later be changed by an administrator.
9. Whether a separate EntityType/schema-classification mechanism should eventually exist alongside Topics.
10. Whether starter content is installed by extension code, Page Exchange packages, XML import, or another mechanism.

---

38. Recommended Implementation Order

Phase 1: Wiki Mode, PageType, PageStatus, Cargo table, basic metadata UI, validation.

Phase 2: Areas, ParentArea, RelatedAreas, hierarchy.

Phase 3: Projects, RelatedProjects, Project-to-Area default copying.

Phase 4: Topic namespace, Topic table, RelatedTopics, Topic hub pages.

Phase 5: Wiki Health dashboard, unclassified warnings, archive filtering.

Phase 6: starter-page onboarding, type-specific metadata framework, topic-specific metadata framework, API, and maintenance tools.

Each phase should include automated tests before proceeding.

---

39. Testing Requirements

Automated tests shall cover at least:

PageType validation
PageStatus validation
status/type compatibility
ParentArea validation
Area cycle detection
Area selector filtering
Project selector filtering
Topic selector filtering
RelatedAreas list persistence
RelatedProjects list persistence
RelatedTopics list persistence
Project Area default copying
archived object behavior
unclassified detection
permissions-aware query output
page rename handling
page deletion/dangling-reference detection
API validation

Use MediaWiki-supported unit/integration test frameworks appropriate to the installed version.

---

40. Coding Standards

The implementation shall follow MediaWiki extension conventions, use namespaced PHP classes, avoid deprecated APIs, use dependency injection where supported, validate on the server, escape user output, respect CSRF protection, respect MediaWiki permissions, document configuration/schema, provide upgrade logic for schema changes, and include automated tests for core business rules.

Avoid duplicating business rules independently in PHP and JavaScript where a server-side source of truth is practical.

---

41. Naming Standard

Canonical internal names:

WikiMode
PageType
PageStatus
ParentArea
RelatedAreas
RelatedProjects
RelatedTopics
TopicName
TopicStatus

Recommended user-facing labels:

Wiki Mode
Type
Status
Parent Area
Related Areas
Related Projects
Topics

Avoid underscores such as Page_Type unless required by a specific external convention. Avoid numbered relationship properties.

---

42. Summary of Core Business Rules

Every PARA knowledge page:
    exactly one PageType
    exactly one valid PageStatus

If PageType = Area:
    zero or one ParentArea
    no RelatedAreas

If PageType != Area:
    no ParentArea
    zero or more RelatedAreas

Any normal page:
    zero or more RelatedProjects
    zero or more RelatedTopics

Topics:
    first-class classification objects
    not PageTypes
    recommended dedicated namespace

Archived:
    lifecycle state
    not security state

Project Area behavior:
    defaults copied at assignment time
    not permanently inherited

Unclassified:
    warning/report condition
    not a save-blocking error

This model shall be treated as the implementation source of truth unless superseded by a later approved specification.

Dynamic Hub Pages and Navigation

Purpose

Areas, Projects, and Topics shall function as navigational hubs in addition to storing user-authored content.

The system-generated relationship information shall be derived from structured metadata and shall not require the user to manually maintain lists of related pages.

The implementation should use one generalized Hub Page subsystem rather than separate unrelated implementations for Areas, Projects, and Topics.

Hub Page Types

The Hub Page subsystem shall apply to:

• pages whose PageType=Area
• pages whose PageType=Project
• pages in the Topic: namespace

The relationship used to populate the dynamic page list depends on the hub type:

Hub type	Relationship query
Area	Pages whose RelatedAreas contains the current Area
Project	Pages whose RelatedProjects contains the current Project
Topic	Pages whose RelatedTopics contains the current Topic

Hub Page Layout

The rendered page should conceptually contain:

Page title
Editable introductory content
System-generated hub section
Optional editable additional content

The generated section shall not be directly editable and shall not be saved as ordinary wikitext.

Preferred long-term architecture:

main revision-backed content slot
system-generated hub component
secondary revision-backed content slot (optional lower content)

Before implementing a secondary slot, verify compatibility with the installed MediaWiki version and VisualEditor. If this materially increases version 1 complexity, version 1 may append the generated hub after the main editable content and defer lower editable content.

Area Hub Pages

An Area page shall automatically display:

• its Parent Area, when one exists
• its immediate child Areas
• pages directly associated with the Area
• sorting controls

Child Areas are derived from:

ParentArea = current Area

Directly associated pages are derived from:

RelatedAreas HOLDS current Area

Direct relationships shall be the default. Descendant content may optionally be included through a control such as "Include pages from sub-areas". Descendant inclusion shall be computed from the hierarchy; ancestor Areas shall not be redundantly written into RelatedAreas.

Project Hub Pages

A Project page shall automatically display:

• Project metadata
• Related Areas
• pages whose RelatedProjects contains the current Project
• sorting controls

Project-specific metadata such as target date, completion date, progress, or outcome may be displayed when implemented.

Topic Hub Pages

A Topic page shall automatically display:

• user-authored Topic description
• pages whose RelatedTopics contains the current Topic
• sorting controls
• optional derived counts grouped by PageType

The counts and lists shall be dynamically derived and not manually maintained.

Hub List Sorting

Every generated relationship list shall support:

• Page Name
• Creation Date
• Last Edit Date

The query layer shall support ascending and descending order.

Recommended user-facing choices:

Name A-Z
Name Z-A
Newest Created
Oldest Created
Recently Updated
Least Recently Updated

Default: Name A-Z, unless configured otherwise.

Hub List Filtering

The architecture shall support future filters including:

• PageStatus
• PageType
• direct relationships versus descendant Area relationships

Archived content should be excluded from normal hub lists by default where appropriate and exposed through an explicit filter.

Page Creation and Last-Edit Dates

MediaWiki revision history shall remain authoritative for creation and last-edit timestamps.

For efficient querying and sorting, the application may maintain indexed/cached values:

CreatedAt
UpdatedAt

The implementation shall document how they are populated and refreshed and should avoid querying the earliest revision of every result during ordinary rendering.

Permissions

All generated Hub content shall respect MediaWiki read permissions and future sharing/ACL rules.

A viewer shall not learn the title, existence, metadata, or count contribution of a page they cannot view.

This applies to relationship lists, child Areas, counts, filters, autocomplete, Topic breakdowns, Main Page lists, and APIs.

Pagination and Performance

Generated lists shall support pagination and server-side sorting for large result sets.

The implementation should use indexed query fields, avoid full-table scans, use MediaWiki caching where appropriate, and invalidate/refresh cached output when relevant relationships or metadata change.

The subsystem should remain practical for hubs containing thousands of related pages.

Empty States

Hub pages shall render useful empty-state messages, such as:

No pages are currently associated with this Area.
No pages are currently assigned to this Project.
No pages currently use this Topic.

Main Page Dashboard

In PARA Wiki mode, the Main Page shall provide generated navigation in addition to user-configurable introductory content.

At minimum it shall display:

• a hierarchical list of active Areas
• Active Projects

Area Hierarchy

Top-level Areas are:

PageType = Area
PageStatus = Active
ParentArea = NULL

Each top-level Area shall display active child Areas recursively or to a configurable display depth.

The hierarchy shall be derived from ParentArea, never manually maintained.

Archived Areas shall be excluded by default.

Active Projects

The Main Page shall display:

PageType = Project
PageStatus = Active

Each title shall link to its Project hub page.

Provide a link to an All Projects view that can include Inception and Archived Projects.

The initial Main Page should remain concise; recently edited pages, unclassified counts, and Wiki Health summaries may be added later.

System Index Pages

The extension shall provide generated index views for:

• All Areas
• All Projects
• All Topics
• Wiki Health
• Unclassified Pages

Where practical these should be MediaWiki Special pages rather than editable normal pages.

Recommended routes:

Special:Areas
Special:Projects
Special:Topics
Special:WikiHealth
Special:UnclassifiedPages

All Areas

Support hierarchical display, Active/Archived filtering, links to Area hubs, and optional direct/descendant page counts.

All Projects

Support PageStatus filtering, Area filtering, sorting by Page Name/Creation Date/Last Edit Date, and links to Project hubs.

All Topics

At minimum show Topic name, link, Active/Archived filtering, and count of accessible pages using the Topic.

Recommended sorting:

Name
Number of Pages
Recently Used
Creation Date
Last Edit Date

Potential future maintenance views include unused Topics, Topics without descriptions, archived Topics, and possible duplicates.

Hub Subsystem Technical Architecture

Implement a generalized service rather than independent Cargo queries embedded in templates.

Recommended conceptual components:

Component	Responsibility
HubService	Determine whether the current page is a Hub and assemble its view model.
HubQueryService	Retrieve related pages using the appropriate relationship.
HubRenderer	Render generated Hub sections.
AreaHierarchyService	Resolve parents, children, descendants, and cycle-safe traversal.
HubSort	Validate and translate supported sort modes.
HubFilter	Validate and apply supported filters.

Templates may assist presentation, but relationship selection, permissions, hierarchy traversal, sorting, and validation shall reside in extension code.

Relationship mapping:

Area    -> RelatedAreas
Project -> RelatedProjects
Topic   -> RelatedTopics

Adding a future Hub-capable object should not require rewriting the subsystem.

Additional API Requirements for Hubs and Indexes

The API shall additionally support operations equivalent to:

Get hub metadata
List pages related to an Area
List pages related to a Project
List pages related to a Topic
List child Areas
List Area descendants
List Area hierarchy
List Projects by status
List Topics

List operations shall support pagination and, where relevant:

sort
direction
status
pageType
includeArchived
includeDescendants
limit
continuation

Exact names shall follow MediaWiki/API conventions.

Additional Acceptance Criteria for Dynamic Hubs

Scenario K: Area Hub

Given Personal as an Active Area and several pages with RelatedAreas=Personal:

• Personal automatically lists those pages.
• no manually maintained list is required
• changing RelatedAreas updates Hub membership
• generated list is not editable as ordinary page text

Scenario L: Hub Sorting

Given related pages with different names, creation dates, and edit dates:

• sort alphabetically
• sort by creation date
• sort by last edit date
• sorting does not modify metadata
• sorting works with pagination

Scenario M: Area Hierarchy

Given Photography and Cooking with ParentArea=Hobbies:

• Hobbies displays them as children
• each child displays Hobbies as parent
• hierarchy is generated from ParentArea

Scenario N: Direct Area Relationships

Given Canon EOS R10 with RelatedAreas=Photography:

• it appears in Photography's direct list
• it does not appear in Hobbies' direct list solely because Photography is beneath Hobbies
• a descendant-inclusive view may include it

Scenario O: Project Hub

Given Hotels in Rome with RelatedProjects=Plan Italy vacation:

• Plan Italy vacation automatically lists Hotels in Rome
• Project Areas are displayed
• generated list is not directly editable

Scenario P: Topic Hub

Given Topic:Python and multiple pages using it:

• Topic:Python lists accessible associated pages
• it may display derived PageType counts
• archiving the Topic does not destroy relationships

Scenario Q: Main Page Area Tree

• active top-level Areas render hierarchically
• child Areas appear beneath parents
• archived Areas are excluded by default
• links point to Area hubs

Scenario R: Main Page Projects

• Active Projects display by default
• Inception and Archived Projects do not
• All Projects view can expose other statuses

Scenario S: Topics Index

• Special:Topics lists accessible Topics
• Topics can be sorted by name
• usage counts respect permissions
• archived Topics can be filtered

Scenario T: Hub Permissions

• inaccessible related pages are not displayed
• inaccessible titles do not contribute to exposed counts
• API behavior matches rendered-page behavior

Additional Open Design Questions

1. Whether version 1 supports editable content both above and below the generated Hub section, or initially only before it.
2. Whether a secondary MediaWiki content slot provides acceptable VisualEditor behavior.
3. Whether descendant-Area inclusion ships in version 1 or is deferred.
4. Whether Hub sort/filter preferences are temporary, per-user, or per-Hub.
5. Exact default pagination size.
6. Whether Topic PageType breakdown counts ship in version 1.
7. Whether Main Page dashboard sections are configurable/reorderable in version 1.
8. Whether system indexes also expose transcludable components in addition to Special pages.