docs(coreprotect): document player position pings (a:ping)

projects/CoreProtect/docs/commands.md

@@ -198,6 +198,7 @@ ___
 | `a:session` | player logins/logouts |
 | `a:+session` | player logins |
 | `a:-session` | player logouts |
+| `a:ping` | where online players were, logged once a minute (see `player-pings`) |
 | `a:sign` | messages written on signs |
 | `a:username` | username changes |
 
@@ -282,8 +283,10 @@ Lookup commands are generally the same as rollback commands. The primary differe
   *(lookup inventory transactions by Notch in the last 3 days)*
 * `/co lookup u:Notch a:login`  
   *(lookup all logins ever done by Notch)*
-* `/co lookup u:Notch a:login`  
-  *(lookup all logins ever done by Notch)*
+* `/co lookup u:Notch t:2h a:ping`  
+  *(lookup where Notch was each minute over the last 2 hours)*
+* `/co lookup u:Notch t:1d a:session,ping`  
+  *(lookup Notch's logins, logouts and positions over the last day)*
 * `/co lookup u:Notch a:username`  
   *(lookup previous usernames used by Notch)*
 

projects/CoreProtect/docs/config.md

@@ -51,6 +51,18 @@ Create the configured database first with a database engine that provides persis
 
 Multiple active CoreProtect installations may share one ClickHouse database and prefix when `database-lock` is disabled. Configure every installation to use the same CoreProtect version, direct endpoint to the same physical ClickHouse server, and prefix, with a separate CoreProtect data directory; do not use a load balancer across independent nodes. Keep their system clocks synchronized; events recorded by different installations in the same second have an unspecified relative order. A shared prefix is one logical namespace: use globally unique world names unless same-named worlds are intentionally the same world, because their coordinate history is combined. Player attribution assumes that a username is not reassigned to a different account within that namespace and that a UUID-bearing login precedes UUID-less activity under a changed name. UUID-bearing observations preserve an account ID through ordinary username changes, but simultaneous username changes and username reuse are outside the base shared-writer contract. A server may continue displaying a peer's previously cached username until it observes that player locally or CoreProtect reloads. ClickHouse has no cross-server maintenance fence without Keeper, so every purge is rejected while `database-lock` is disabled. To purge a shared namespace, stop every installation sharing it, enable `database-lock` on the one installation that will run the purge, and restart or reload that installation before purging. Follow the same stop-all rule before a database migration; the migration command updates only the installation that runs it, so update the other configurations before restarting them. Replicated and distributed tables remain unsupported.
 
+## Player Position Pings
+
+`player-pings` logs where each online player is at a fixed interval, in seconds:
+
+```yaml
+player-pings: 60
+```
+
+Each ping is stored in the session table alongside logins and logouts, with the player's world and block coordinates. A player's first ping comes one interval after they join. Set the value to `0` to disable pings; a per-world config can disable them in one world. Changes take effect after `/co reload`.
+
+Search pings with `/co lookup u:<player> a:ping`; `a:session` lists only logins and logouts. Purges remove old pings with the rest of the session history. One row per online player per minute is small: about 0.5 GB a year in SQLite for an average of 15 players online.
+
 ## Per-World Configuration
 
 If you'd like to modify the logging settings for a specific world, simply do the following:

projects/CoreProtect/docs/permissions.md

@@ -80,7 +80,7 @@ The following permissions can be used to restrict functionality within the plugi
   Can be optionally used as a negative permission to prevent lookups via the near command.  
    
 * **coreprotect.lookup.session** *(default: op)*  
-  Can be optionally used as a negative permission to prevent session lookups.  
+  Can be optionally used as a negative permission to prevent session lookups, including position pings (`a:ping`).  
    
 * **coreprotect.lookup.sign** *(default: op)*  
   Can be optionally used as a negative permission to prevent sign lookups.