Repository navigation
Documentation Guide
This wiki is the canonical home for both project-wide and v3 implementation documentation. Project concepts and v3 implementation contracts have separate page responsibilities within this wiki.
| Repository | Maintained content |
|---|---|
kpl-v3.wiki |
Project concepts, research/publications, all operator/developer guides, schemas/formulas, navigation, and documentation images |
kpl-v3 |
Source code, deployment files, executable examples, tests, machine-readable validation inputs, and README links to the wiki |
Within the wiki, ask “Would this remain true if the implementation changed?” Stable intent belongs to project pages; behavior tied to a software revision belongs to v3 pages. Link between the two instead of duplicating a contract.
| Topic | Project pages | v3 implementation pages |
|---|---|---|
| Purpose and capabilities | Research objectives and design principles | Current supported features, prerequisites, and limitations |
| Architecture | Control, distributed execution, observation, and their conceptual relationships | Processes, services, networks, permissions, persistence, failure boundaries, and source map |
| Capacity and placement | Requested population vs. admitted capacity vs. observed readiness | CLI defaults, Agent overrides, scheduling algorithm, acknowledgments, reservations, and cleanup |
| Experiment lifecycle | Design, evidence collection, comparison, and recovery provenance | YAML actions, timing, run/batch states, stopping, continuation, and retry |
| Measurement | Population, uncertainty, units, and fair reporting principles | Exact formulas, definition versions, events, fields, aggregation, and known gaps |
| Operations and access | Link to the chosen implementation | Deployment, accounts, authentication, logs, SSE, troubleshooting, backups, and retention |
| Analysis and figures | Interpretation and comparability requirements | Analysis jobs, chart controls, export formats, and stored artifacts |
| History and publications | Project lineage, bibliographic records, and citation guidance | Compatibility mappings, migrations, source inventories, benchmarks, and validation evidence for that version |
A v2 compatibility table for v3 belongs with v3 compatibility pages. A publication about v2 belongs in Publications. Performance evidence stays with its implementation scope, fixture, environment, and limitations.
Project purpose, concepts, research, and publications are maintained directly in these wiki pages.
| Document | Responsibility |
|---|---|
| Project overview | Short project introduction, reading paths, repository boundary, and version lineage |
| CONCEPTS | Design principles, logical architecture, capacity and workload concepts |
| RESEARCH | Research questions, experiment cycle, reporting rules, and measurement background |
| PUBLICATIONS | Platform publications, studies using K-P2PLab, and citation guidance |
| This document | Ownership, splitting, navigation, and maintenance rules for the unified wiki |
Keep operational examples and current capabilities in v3 pages. The kpl-v3 README provides a short entry point to this wiki. Research-method explanations and publications remain separate because they serve different readers and change for different reasons.
The v3 index groups the implementation pages by reader task.
| Reader task | v3 canonical documents |
|---|---|
| Start and operate the platform | Swarm-Deployment, Agent-Capacity, Monitoring |
| Prepare, execute, stop, and recover experiments | Scenario-Library, Experiments; executable walkthroughs in Churn-Publish-Example |
| Inspect the live network | Dashboard, Topology |
| Preserve, analyze, and export evidence | Results, Visualization |
| Look up exact contracts | Scenario-Reference, Protocol-Options, API, Experiment-Metrics, Bandwidth |
| Understand or change the implementation | Architecture, Development, Churn-Performance |
| Compare with earlier implementations | V2-Reproduction, V2-Analysis-Coverage |
Monitoring owns Prometheus/Grafana, access logs, and connection diagnosis. Results owns retained files and export/backup boundaries. Experiments owns execution and recovery. API owns HTTP payloads, status codes, SSE framing, and cache semantics. Metric and bandwidth pages own formulas; Visualization owns chart operation.
Split when the reader's task or the content's owner changes. Do not split solely because a file is long, or create a new page for every bug fix.
- Keep a procedure's prerequisites, steps, outcome, and failure handling together.
- Separate procedures from exhaustive schemas and formulas; link to the relevant reference section.
- Separate live observation, retained source results, computed analysis, and monitoring history because their lifetimes differ.
- Keep related protocol options and metric definitions together when users need to compare them.
- Put measured optimization and historical validation evidence in development or compatibility material, with its date, inputs, and limits. Do not present it as validation of a later checkout.
English is the primary documentation: Home.md is the main entry point, and the default sidebar, index, and footer use English. _Sidebar.md keeps Korean navigation in a collapsed 한국어 문서 section. Home-KO.md is the landing page for those translations. English pages link to their Korean translation at the bottom; Korean pages link back to their section and the corresponding English original at the top.
Use stable, flat ASCII page names such as Agent-Capacity.md and Agent-Capacity-KO.md; the Korean subsection is organized through navigation while existing page URLs remain stable. Update the English original first and keep Korean section coverage, examples, and destinations aligned with it. Keep actual English UI labels in Korean instructions.
Use full wiki URLs for Markdown links, without .md, for example [Agent capacity](https://github.com/k-p2p-lab/kpl-v3/wiki/Agent-Capacity). Preserve section anchors when editing a page. Code, directory, and example links must use the kpl-v3 repository’s blob/tree URLs; local ../internal paths resolve in the wiki repository and cannot identify v3 sources. Wiki images live under images/ and use raw wiki URLs.
When code behavior changes, update its owning wiki page and Korean pair with the corresponding source revision. Keep Home, the index, and Sidebar aligned when adding or renaming pages. The kpl-v3 README is a short entry point. Keep documentation and images in the wiki; do not recreate a docs directory in v3.
Clone the wiki independently when working locally:
git clone https://github.com/k-p2p-lab/kpl-v3.wiki.git
cd kpl-v3.wikiEdit Markdown pages here. Run application, Swarm, and development commands from the kpl-v3 source checkout. The wiki stores documentation only; it is not an application checkout. A wiki commit and a v3 commit have independent histories: record the source commit when retaining benchmark or validation evidence.
Before publishing, check page/anchor links, same-language destinations, source-file links, images, Sidebar/index reachability, tables, code fences, and structured examples. Documentation checks do not establish runtime behavior. Historical tests are not checks performed on a later revision.
GitHub documents wiki links and images, sidebar/footer files, collapsed sections, and editing/publishing a wiki Git repository.
The migration imported 56 Markdown documents (28 English/Korean pairs), including the original repository introductions and the v3 index. The migration map records each original path, content hash, destination, and source revision. The table below identifies the migration baseline, not the current application revision.
| Source | Migration baseline |
|---|---|
| Former project repository | b399b16f3a520692aa64ec282eb21f86c2cb1538 |
| v3 | c20624ac6d21 |
The former Hub repository is retired; its content, logo, and diagrams are owned by this wiki. The v3 docs directory, including its entry stubs and architecture image, has been removed. The migration map retains former path/revision identifiers solely as provenance; it requires no access to the old repository. Wiki Git history tracks subsequent documentation changes. The v2 audit manifest moved to scripts/data/v2-analysis-coverage.json in v3 because the audit script consumes it. It remains versioned with the code, while the explanatory coverage page lives in this wiki.
The wikiAssets entries in the migration map record the original paths, wiki paths, and SHA-256 hashes of the logo and architecture PNG. Conceptual, experiment-cycle, and implementation diagrams are also retained as Mermaid source in their wiki pages.
Korean translation: 한국어.
Home · Documentation guide · kpl-v3 source
Commands run from the kpl-v3 source checkout.