diff --git a/src/suisseid.hxx b/src/suisseid.hxx
index edd7847..907bfd3 100644
--- a/src/suisseid.hxx
+++ b/src/suisseid.hxx
@@ -27,6 +27,54 @@
 //@{
 namespace suisseid {
 
+  /** @page init Initialize Card and Check Status
+
+      An idea on how the smart card status could be evaluated is the
+      following state machine:
+
+      @dot
+      digraph {
+        transportState
+          [URL="\ref cardos::Commands::transportState"];
+        transportPinRetries
+          [URL="\ref cardos::Commands::transportPinRetries"];
+        pkcs15PinRetries
+          [URL="\ref cardos::Commands::pkcs15PinRetries"];
+        sigGPinRetries
+          [URL="\ref cardos::Commands::sigGPinRetries"];
+        pukRetries
+          [URL="\ref cardos::Commands::pukRetries"];
+        changePin
+          [URL="\ref cardos::Commands::changePin"];
+        broken [label="replace card"];
+      
+        start ->  transportState;
+        transportPinRetries -> broken [label="-1"];
+        certsValid -> broken [label="false"];
+        pukRetries -> broken [label="-1"];
+        sigGPinRetries -> broken [label="-1"];
+        transportState -> transportPinRetries [label="true"];
+        transportPinRetries -> changePin [label=">-1"];
+        changePin -> transportState;
+        transportState -> haveCerts [label="false"];
+        haveCerts -> installCerts [label="false"];
+        installCerts -> transportState;
+        haveCerts -> certsValid [label="true"];
+        certsValid -> pkcs15PinRetries [label="true"];
+        pkcs15PinRetries -> sigGPinRetries [label=">-1"];
+        pkcs15PinRetries -> pukRetries [label="-1"];
+        pukRetries -> changePin [label=">-1"];
+        sigGPinRetries -> valid [label=">-1"];
+        {valid broken} -> end;
+
+        {rank=same; valid broken}
+        {rank=same; transportPinRetries haveCerts}
+        {rank=same; certsValid installCerts changePin}
+      }
+      @enddot
+
+      */
+
   //! Represents a SuisseID Card
   /*! This is the parent class for special classes for the respecive
       SuisseID providers. */